Create a contact

post

https://{youraccountname}.api-us1.com/api/3/contacts

Create a brand-new contact. This endpoint fails with a 422 duplicate-email error when a contact with the same email address already exists; it never updates an existing contact. To add or import contacts that may already exist, use POST /contact/sync for one contact or POST /import/bulk_import for many (up to 250 per request) instead: both create or update by email, and the import can also set list subscriptions and tags per contact. The same request can also save custom field values (contact.fieldValues), add tags (contact.tags) and subscribe the contact to lists (contact.lists or contact.form). The user needs the add contacts permission.

🚧
Organization-Related Nodes Have Been Deprecated
Contact-Organization relationships are now managed through Account-Contact end points

📘
Reference a custom field by id- not the custom field's name/title.
When writing to a Contact's custom data, the field must be the id of a previously-created custom field, not the custom field's name/title.

Creating a custom field

Creating a custom field value

Retrieving previously-created custom fields

{
  "contact": {
    "email": "[email protected]",
    "allowNullEmail": true,
    "firstName": "John",
    "lastName": "Doe",
    "phone": "7223224241",
    "fieldValues": [
      {
        "field": "1",
        "value": "The Value for First Field"
      },
      {
        "field": "6",
        "value": "2008-01-20"
      }
    ],
    "tags": [
      "customer",
      "newsletter"
    ]
  }
}

{
      "fieldValues": [
        {
            "contact": "113",
            "field": "1",
            "value": "The Value for First Field",
            "cdate": "2020-08-01T10:54:59-05:00",
            "udate": "2020-08-01T14:13:34-05:00",
            "links": {
                "owner": "https://:account.api-us1.com/api/3/fieldValues/11797/owner",
                "field": "https://:account.api-us1.com/api/3/fieldValues/11797/field"
            },
            "id": "11797",
            "owner": "113"
        },
        {
            "contact": "113",
            "field": "6",
            "value": "2008-01-20",
            "cdate": "2020-08-01T10:54:59-05:00",
            "udate": "2020-08-01T14:13:34-05:00",
            "links": {
                "owner": "https://:account.api-us1.com/api/3/fieldValues/11798/owner",
                "field": "https://:account.api-us1.com/api/3/fieldValues/11798/field"
            },
            "id": "11798",
            "owner": "113"
        }
    ],
    "contact": {
        "email": "[email protected]",
        "cdate": "2018-09-28T13:50:41-05:00",
        "udate": "2018-09-28T13:50:41-05:00",
        "orgid": "",
        "links": {
            "bounceLogs": "https://:account.api-us1.com/api/:version/contacts/113/bounceLogs",
            "contactAutomations": "https://:account.api-us1.com/api/:version/contacts/113/contactAutomations",
            "contactData": "https://:account.api-us1.com/api/:version/contacts/113/contactData",
            "contactGoals": "https://:account.api-us1.com/api/:version/contacts/113/contactGoals",
            "contactLists": "https://:account.api-us1.com/api/:version/contacts/113/contactLists",
            "contactLogs": "https://:account.api-us1.com/api/:version/contacts/113/contactLogs",
            "contactTags": "https://:account.api-us1.com/api/:version/contacts/113/contactTags",
            "contactDeals": "https://:account.api-us1.com/api/:version/contacts/113/contactDeals",
            "deals": "https://:account.api-us1.com/api/:version/contacts/113/deals",
            "fieldValues": "https://:account.api-us1.com/api/:version/contacts/113/fieldValues",
            "geoIps": "https://:account.api-us1.com/api/:version/contacts/113/geoIps",
            "notes": "https://:account.api-us1.com/api/:version/contacts/113/notes",
            "organization": "https://:account.api-us1.com/api/:version/contacts/113/organization",
            "plusAppend": "https://:account.api-us1.com/api/:version/contacts/113/plusAppend",
            "trackingLogs": "https://:account.api-us1.com/api/:version/contacts/113/trackingLogs",
            "scoreValues": "https://:account.api-us1.com/api/:version/contacts/113/scoreValues"
        },
        "id": "113",
        "organization": ""
    }
}

Responses

Language

Credentials

Header

URL

Loading…

Response

Choose an example:

application/json

Organization-Related Nodes Have Been Deprecated

Reference a custom field by id- not the custom field's name/title.

201The contact was created. The body has the new contact under contact and its custom field values under fieldValues.

400The contact was not created: a list in contact.lists or contact.form is an email list and the contact has no email address, or an SMS list and the contact has no phone number. Tags and an account named in the request may already have been created.

404The contact was not created: orgid or organization names an account id that does not exist. Body: message, "No Result found for CustomerAccount with id" followed by that id. Tags and an account named in the request may already have been created.

409The contact was not created: another contact already has this whatsapp_id. Tags and an account named in the request may already have been created.

Reference a custom field by `id`- not the custom field's name/title.