# Add or Update Lead

## Add or Update Lead

<mark style="color:green;">`POST`</mark> `[PlatformAddress]/api/1.0/contact?action=addOrUpdateLead`

Add or update the details of a lead

#### Path Parameters

| Name                 | Type    | Description                                                                                                                                          |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| id                   | integer | The unique identifier of a lead (Leave empty to add the lead to the system)                                                                          |
| qualityId            | integer | The quality of the lead                                                                                                                              |
| industryId           | integer | The unique industry of the lead. (Required when lead belongs to contact and id parameter is missing)                                                 |
| sourceId             | integer | The unique source id of the lead. (Required when the id parameter is missing. )                                                                      |
| companyId            | integer | The unique company id of lead. (Required when lead belongs to company and id parameter is missing)                                                   |
| company              | object  | The data array of company. See addOrUpdateCompany API in contact namespace for parameters. See assigning a company/contact to the lead.              |
| companyLeadContactId | integer | The unique company id of lead (Required when lead belongs to company and id parameter is missing)                                                    |
| contactId            | integer | The unique contact id of lead (Required when lead belongs to contact and id parameter is missing)                                                    |
| contact              | object  | The data array of contact. See addOrUpdateContact API in contact namespace for parameters. See assigning a company/contact to the lead.              |
| name                 | string  | The name for the lead (Required when the id parameter is missing)                                                                                    |
| ownerUserId          | integer | The id of the sales person user assigned to the lead. The privileges of the user assigned to the api key may prevent this from being changed.        |
| typeId               | integer | The type of lead (Required when id parameter is missing)                                                                                             |
| subtypeId            | integer | The sub type of lead (Required when type have sub types)                                                                                             |
| stageId              | integer | The stage of lead (Required when id parameter is missing)                                                                                            |
| stageReasonId        | integer | The unique stage reason id of opportunity                                                                                                            |
| channelId            | integer | The channel Id of lead                                                                                                                               |
| description          | string  | The description for the lead                                                                                                                         |
| customFields         | array   | The custom field values of the lead. A custom field value might be required depending on how it has been configured in the account. See Custom Field |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Custom Field

A lead custom field is an object with the following details.

| Property   | Type    | Required | Description                                                                    |
| ---------- | ------- | -------- | ------------------------------------------------------------------------------ |
| fieldId    | integer | required | The unique id of the lead custom field                                         |
| fieldValue | mixed   | required | The value of the lead custom field. Depends on the type of custom field value. |

## Special Considerations

### Assigning a company/contact to the lead

The *contact type* of a lead is either a *company* **or** a *contact*. When *companyId* **or** *company* is present in the request then the *contact type* of the lead is set to *company*, and the *contactId* **or** *contact* must be a contact that belongs to that company. Otherwise the *contact type* of the lead is set to *contact* and contactId can be any valid contact in the account.

If *contact* and *company* are present in request then it will link given contact to company.

## Returns

| Property | Description                                      |
| -------- | ------------------------------------------------ |
| success  | Whether or not the lead was added to the account |
| id       | The unique id of the lead                        |

## Throws

| Code                 | Description                  |
| -------------------- | ---------------------------- |
| Specific Code: 24215 | The request is empty         |
| Specific Code: 24216 | The lead does not exist      |
| Specific Code: 24218 | The lead details are invalid |

This call takes values for a lead, and either

1. Updates the values for that lead (after you have provided an id in the parameters), or
2. Adds the lead to the system (if the id parameter is missing)

The result of this call will contain the status of the result (either true or false) and the lead identifier of the updated or newly created lead.