# Add or Update Contact
## Add or Update Contact
`POST` `[PlatformAddress]/api/1.0/contact?action=addOrUpdateContact`
Add or update contact details
#### Request Body
| Name | Type | Description |
| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| externalId | string | Reference to the ID of the contact in an external system. |
| id | integer | The contact's identifier. (Leave empty to add new contact) |
| firstName | string | The contact's first name (required when id is missing) |
| LastName | string | The contact's last name (required when id is missing) |
| email | string | The contact's email address. Must be a valid email. (required when id is missing) |
| phone | string | The contacts phone number. |
| groups | string | The array of subscription groups to set for the contact. Note: This list will override any groups currently set for the contact. |
| customFields | string | The array of custom fields to set on the contact. Each field will be validated depending on the type of field that is set. |
| companies | string | The array of companies to set on the contact. Each value will be validated depending on the type of field as well as it will verify that the given company exists or not. |
| status | enum | The contact's email subscription status. |
| smsStatus | enum | The contact's sms subscription status. |
| updateIfExists | boolean | Whether or not to update the contact by firstName, lastName and email when id parameter is missing. |
| externalUrls | array | This is an array of External URL field objects of the contact (a maximum of 3 objects allowed). When set to null, it will remove all externalUrls from the contact. |
{% tabs %}
{% tab title="200 " %}
```
{
"id":33884
}
```
{% endtab %}
{% endtabs %}
## Example Request: Adding a contact
```javascript
{
"firstName": "Bobby",
"lastName": "Smith",
"email": "bobbysmith@hotmail.com",
"groups": [
{
"groupId": 10
}
],
"customFields": [
{
"fieldId": 33443,
"value": "No"
}
],
"companies": [
4,
5
],
"status": 2,
"smsStatus": 2,
"externalId" : "12345",
"externalUrls" : [
{
"ref": "example1",
"label": "Example One",
"url": "https://example1.com"
},
{
"ref": "example2",
"label": "Example Two",
"url": "https://example2.com"
},
{
"ref": "example3",
"label": "Example Three",
"url": "https://example3.com"
}
],
"privacyConsent": true
}
```
## Example Request: Updating a contact
`Note : the groups will be set to only group 10, destroying the existing value`
```javascript
{
"id":33884,
"firstName":"Bobby",
"groups":[{"groupId":10}],
"customFields":[{"fieldId":33443,"value":"No"}],
"companies":[4,5],
"status": 2,
"smsStatus": 2,
}
```
This call takes values for a contact, and either
1. Updates the values for that contact (after you have provided an id in the parameters), or
2. Adds the contact 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 contact identifier of the updated or newly created contact.
The properties of the contact currently supported are:
* firstName
* lastName
* email
* phone
* groups
* This is an array of group objects with the ‘groupId’ key.
* customFields
* This is an array of custom field objects with ‘fieldId’ and ‘value’ keys
* Companies
* This is an array of companies Ids
* status
* The current status of the email susbcription in contact. The value of this field will be [one of the following current status](#email-status)
* smsStatus
* The current status of the sms susbcription in contact. The value of this field will be [one of the following current status](#sms-status)
* externalUrls
* This is an array of External URL field objects of the contact (a maximum of 3 objects allowed). When set to null, it will remove all externalUrls from the contact. [ExternalUrl field](#external-url-field)
* privacyConsent
* Whether or not giving privacy consent for this contact.
## Returns
| Property | Description |
| -------- | ------------------------------------------------ |
| success | If the contact was successfully added or updated |
| id | The unique identifier for the contact |
| message | Message of the failure (if success was false) |
### Email Status
The status is the record of whether the contact has opted in to email communication.
| | |
| ----- | --------------- |
| **#** | **Description** |
| 1 | Subscribed |
| 2 | Unsubscribed |
| 3 | Bounced |
| 5 | No Marketing |
### Sms status
The sms status is the record of whether the contact has opted in to sms communication.
| | |
| ----- | --------------- |
| **#** | **Description** |
| 1 | Subscribed |
| 2 | Unsubscribed |
| 3 | Failed |
| 4 | No Marketing |
## External URL Field
An External URL field is an object with the following details.
| Property | Type | Required | Description |
| -------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ref | string | required | The unique reference key of the external URL |
| url | string | optional | The url link (https) scheme eg. When the value is null, the external url record will be removed based on the provided reference key. |
| label | string | optional | The label of the URL to display. |