# Adds a lead to the campaign associated with the API key

`POST` `/api/v1/leads`

Adds a lead to the campaign associated with the API key.

## Request

### Headers

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `x-api-key` | string | yes | The Aktify-provided API key. |

### Body

Content type: `application/json` (required)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `phoneNumber` | string | yes | The phone number of the lead (equivalent to "phone" in the legacy leads_v2 API). (Example: `(509) 555-1234`) |
| `region` | string | no | The region of the lead. Required if zipCode is not provided. Restricted to US state codes. (Example: `CA`) |
| `zipCode` | string | no | The zip code of the lead. Required if region is not provided. Will be used to determine region. (Example: `90210`) |
| `email` | string | no | The email of the lead (Example: `someone@example.com`) |
| `externalCreated` | string | no | The external creation time of the lead in ISO8601 format (equivalent to "ext_created" in the legacy leads_v2 API). This attribute of the lead will be used if the campaign posting strategy is batched and prioritized earliest first or latest first by the lead creation time. (Example: `2022-11-15T21:04:28-0600`) |
| `externalLeadId` | string | no | The external lead ID of the lead (equivalent to "ext_lead_id" in the legacy leads_v2 API). (Example: `myCustomLeadId`) |
| `firstName` | string | no | The first name of the lead (equivalent to "first_name" in the legacy leads_v2 API). (Example: `John`) |
| `lastName` | string | no | The last name of the lead (equivalent to "last_name" in the legacy leads_v2 API). (Example: `Smith`) |
| `source` | string | no | The source of the lead. This should be provided if you have configured your campaign outreach templates to use a LEAD_SOURCE replacement. (Example: `myCustomSource`) |
| `link` | string | no | The link you would like to send to the lead. This should be provided if you are submitting a lead for a link-click campaign. Mutually exclusive parameter with "linkToShorten" (one or the other must be provided, but not both). (Example: `https://www.aktify.com`) |
| `metadata` | object | no | Optional metadata associated with the lead. Must be a key-value object where all values are strings. (Example: `{"customField1":"value1","customField2":"value2"}`) |
| `linkToShorten` | string | no | The link you would like for Aktify to shorten, then send to the lead. This should be provided if you are submitting a lead for a link-click-with-click-tracking campaign. Mutually exclusive parameter with "link" (one or the other must be provided, but not both). (Example: `https://www.aktify.com`) |

## Responses

### 201

The created lead with whatever properties were accepted.

Response body (`application/json`):

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `phoneNumber` | string | yes | The phone number of the lead (equivalent to "phone" in the legacy leads_v2 API). (Example: `(509) 555-1234`) |
| `region` | string | no | The region of the lead. Required if zipCode is not provided. Restricted to US state codes. (Example: `CA`) |
| `zipCode` | string | no | The zip code of the lead. Required if region is not provided. Will be used to determine region. (Example: `90210`) |
| `email` | string | no | The email of the lead (Example: `someone@example.com`) |
| `externalCreated` | string | no | The external creation time of the lead in ISO8601 format (equivalent to "ext_created" in the legacy leads_v2 API). This attribute of the lead will be used if the campaign posting strategy is batched and prioritized earliest first or latest first by the lead creation time. (Example: `2022-11-15T21:04:28-0600`) |
| `externalLeadId` | string | no | The external lead ID of the lead (equivalent to "ext_lead_id" in the legacy leads_v2 API). (Example: `myCustomLeadId`) |
| `firstName` | string | no | The first name of the lead (equivalent to "first_name" in the legacy leads_v2 API). (Example: `John`) |
| `lastName` | string | no | The last name of the lead (equivalent to "last_name" in the legacy leads_v2 API). (Example: `Smith`) |
| `source` | string | no | The source of the lead. This should be provided if you have configured your campaign outreach templates to use a LEAD_SOURCE replacement. (Example: `myCustomSource`) |
| `link` | string | no | The link that will be sent to the lead. (Example: `https://shortlink.aktify.com/abcd1234`) |
| `metadata` | object | no | Optional metadata associated with the lead. Must be a key-value object where all values are strings. (Example: `{"customField1":"value1","customField2":"value2"}`) |

### 400

Returned if required fields are missing or any provide field is invalid. Additional details may be in the response body but are not included in the API contract.

### 401

Returned if the request was not authorized with a valid x-api-key header. Additional details may be in the response body but are not included in the API contract.

### 409

Returned if the phone number was already submitted to the campaign. Additional details may be in the response body but are not included in the API contract.