Records

List values for record field

get

Useful when retrieving all values from a summarized relationship field

Authorizations

businessId & userId & apiKey

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

X-API-KEYstringRequired

Path parameters

entity_idstring · uuidRequired

field_idstring · uuidRequired

Query parameters

pageintegerOptional

A page number within the paginated result set.

page_sizeintegerOptional

Number of results to return per page.

searchstringOptional

Responses

200Success

application/json

get

/api/records/{entity_id}/field-values/{field_id}

HTTPcURLJavaScriptPython

GET /api/records/{entity_id}/field-values/{field_id} HTTP/1.1
Host: 
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
X-API-KEY: YOUR_API_KEY
Accept: */*

200Success

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "first_name": "text",
      "last_name": "text",
      "full_name": "text",
      "email": "text",
      "display_name": "text"
    }
  ],
  "errors": [
    "error message"
  ]
}

get

Get entity record by ID

Authorizations

businessId & userId & apiKey

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

X-API-KEYstringRequired

Path parameters

entity_idstringRequiredPattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$

object_identifierstringRequired

Query parameters

detail_summarybooleanOptional

Include summary data in the response, including lead sources.

field_categorystringOptional

Comma separated category ids, to filter by field category. Ignored when field_ids is present.

field_idsstringOptional

Comma separated field ids to include in response. If present but empty, it will return default fields only.

field_namesstringOptional

Comma separated field names to include in response. If present but empty, it will return default fields only.

include_hidden_fieldsbooleanOptional

Include hidden fields in the response.

Responses

200Success

application/json

get

/api/records/{object_identifier}/{entity_id}

HTTPcURLJavaScriptPython

GET /api/records/{object_identifier}/{entity_id} HTTP/1.1
Host: 
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
X-API-KEY: YOUR_API_KEY
Accept: */*

200Success

{
  "object_type": "string",
  "num_upcoming_activities": 0,
  "fields": {},
  "id": "18ff12e2-c4a0-4000-89e6-9b216dd9d801",
  "num_associated_team_members": 0,
  "client_info": {
    "num_addresses_v2": 0,
    "display_name": "string",
    "email_on_suppression_list": false
  },
  "access": {
    "view": true,
    "edit": true,
    "remove": true
  },
  "first_lead_source": {
    "id": "18ff12e2-c4a0-4000-8e84-0f8bb0dafb01",
    "type": "organic_search",
    "client": "18ff12e2-c4a0-4000-8dda-0175712cda01",
    "custom_object_record": "18ff12e2-c4a0-4000-831e-88c0810f2401",
    "source": "string",
    "campaign": "string",
    "medium": "string",
    "term": "string",
    "content": "string",
    "created": "1970-01-01T00:00:00.000Z",
    "_display": {
      "type": "string",
      "source": "string",
      "campaign": "string",
      "medium": "string",
      "term": "string",
      "content": "string"
    }
  },
  "last_lead_source": {
    "id": "18ff12e2-c4a0-4000-8fe9-71a84bc6c101",
    "type": "organic_search",
    "client": "18ff12e2-c4a0-4000-8803-a33e719dc801",
    "custom_object_record": "18ff12e2-c4a0-4000-8c84-44d6dd2b6f01",
    "source": "string",
    "campaign": "string",
    "medium": "string",
    "term": "string",
    "content": "string",
    "created": "1970-01-01T00:00:00.000Z",
    "_display": {
      "type": "string",
      "source": "string",
      "campaign": "string",
      "medium": "string",
      "term": "string",
      "content": "string"
    }
  },
  "lead_source_types": [
    {
      "value": "organic_search",
      "label": "string"
    }
  ]
}

put

Update entity record

Authorizations

businessId & userId & apiKey

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

X-API-KEYstringRequired

Path parameters

entity_idstringRequiredPattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$

object_identifierstringRequired

Body

application/json

archived_conflictone of | nullableOptional

Updates the identifier of matching archived record to not raise a conflict.

• overwrite - overwrite

string · enumOptional

• overwrite - overwrite

Possible values:

or

undefined · enumOptionalPossible values:

Responses

200Success

application/json

400Error

application/json

put

/api/records/{object_identifier}/{entity_id}

HTTPcURLJavaScriptPython

PUT /api/records/{object_identifier}/{entity_id} HTTP/1.1
Host: 
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 804

{
  "fields": [
    {
      "id": "<integer_field_id>",
      "value": 100
    },
    {
      "id": "<primary_field_id>",
      "value": "<record_id>"
    },
    {
      "id": "<primary_field2_id>",
      "value": {
        "id": "<record_id>"
      }
    },
    {
      "id": "<primary_record_field_id>",
      "value": {
        "name": "<record_name>"
      }
    },
    {
      "id": "<primary_contact_field_id>",
      "value": {
        "email": "<contact_email>"
      }
    },
    {
      "id": "<team_selector_field_id>",
      "value": {
        "email": "<team_email>"
      }
    },
    {
      "id": "<rating_field_id>",
      "value": 5
    },
    {
      "id": "<rating_field_id>",
      "value": {
        "id": "<rating_option_id>"
      }
    },
    {
      "name": "email_status",
      "value": {
        "id": "<option_id>"
      }
    },
    {
      "name": "email_status",
      "value": {
        "name": "Opted In"
      }
    },
    {
      "name": "text_field",
      "value": "text"
    },
    {
      "name": "dropdown_field",
      "value": {
        "id": "<option_id>"
      }
    },
    {
      "name": "dropdown_field",
      "value": {
        "name": "<option_name>"
      }
    },
    {
      "name": "dropdown_field2",
      "value": "<option_id>"
    }
  ],
  "archived_conflict": "overwrite"
}

Single value fieldsMulti value fields

{
  "object_type": "text",
  "num_upcoming_activities": 1,
  "fields": {
    "id": {
      "id": "text",
      "field_type": "text",
      "display_name": "text",
      "value": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  },
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "client_info": {
    "num_addresses_v2": 1,
    "display_name": "text",
    "email_on_suppression_list": true
  },
  "access": {
    "view": true,
    "edit": true,
    "remove": true
  },
  "num_associated_team_members": 1,
  "lead_source_types": [
    {
      "value": "organic_search",
      "label": "text"
    }
  ]
}

delete

Archive entity record

Authorizations

businessId & userId & apiKey

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

X-API-KEYstringRequired

Path parameters

entity_idstringRequiredPattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$

object_identifierstringRequired

Responses

204

No response body

delete

/api/records/{object_identifier}/{entity_id}

HTTPcURLJavaScriptPython

DELETE /api/records/{object_identifier}/{entity_id} HTTP/1.1
Host: 
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
X-API-KEY: YOUR_API_KEY
Accept: */*

204

No response body

No content

patch

Update entity record (partial)

Authorizations

businessId & userId & apiKey

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

X-API-KEYstringRequired

Path parameters

entity_idstringRequiredPattern: ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}$

object_identifierstringRequired

Query parameters

return_all_fieldsbooleanOptional

If true, return all fields even if not updated

Body

application/json

archived_conflictone of | nullableOptional

Updates the identifier of matching archived record to not raise a conflict.

• overwrite - overwrite

string · enumOptional

• overwrite - overwrite

Possible values:

or

undefined · enumOptionalPossible values:

Responses

200Success

application/json

400Error

application/json

patch

/api/records/{object_identifier}/{entity_id}

HTTPcURLJavaScriptPython

PATCH /api/records/{object_identifier}/{entity_id} HTTP/1.1
Host: 
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 804

{
  "fields": [
    {
      "id": "<integer_field_id>",
      "value": 100
    },
    {
      "id": "<primary_field_id>",
      "value": "<record_id>"
    },
    {
      "id": "<primary_field2_id>",
      "value": {
        "id": "<record_id>"
      }
    },
    {
      "id": "<primary_record_field_id>",
      "value": {
        "name": "<record_name>"
      }
    },
    {
      "id": "<primary_contact_field_id>",
      "value": {
        "email": "<contact_email>"
      }
    },
    {
      "id": "<team_selector_field_id>",
      "value": {
        "email": "<team_email>"
      }
    },
    {
      "id": "<rating_field_id>",
      "value": 5
    },
    {
      "id": "<rating_field_id>",
      "value": {
        "id": "<rating_option_id>"
      }
    },
    {
      "name": "email_status",
      "value": {
        "id": "<option_id>"
      }
    },
    {
      "name": "email_status",
      "value": {
        "name": "Opted In"
      }
    },
    {
      "name": "text_field",
      "value": "text"
    },
    {
      "name": "dropdown_field",
      "value": {
        "id": "<option_id>"
      }
    },
    {
      "name": "dropdown_field",
      "value": {
        "name": "<option_name>"
      }
    },
    {
      "name": "dropdown_field2",
      "value": "<option_id>"
    }
  ],
  "archived_conflict": "overwrite"
}

Single value fieldsMulti value fields

{
  "object_type": "text",
  "num_upcoming_activities": 1,
  "fields": {
    "id": {
      "id": "text",
      "field_type": "text",
      "display_name": "text",
      "value": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  },
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "client_info": {
    "num_addresses_v2": 1,
    "display_name": "text",
    "email_on_suppression_list": true
  },
  "access": {
    "view": true,
    "edit": true,
    "remove": true
  },
  "num_associated_team_members": 1,
  "lead_source_types": [
    {
      "value": "organic_search",
      "label": "text"
    }
  ]
}

post

Create entity record

Authorizations

businessId & userId & apiKey

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

X-API-KEYstringRequired

Path parameters

object_identifierstringRequired

Body

application/json

unarchiveone of | nullableOptional

string · enumOptional

• prompt - prompt
• unarchive - unarchive
• overwrite - overwrite

Possible values:

or

undefined · enumOptionalPossible values:

Responses

200Success

application/json

400Error

application/json

post

/api/records/{object_identifier}/add

HTTPcURLJavaScriptPython

POST /api/records/{object_identifier}/add HTTP/1.1
Host: 
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 793

{
  "fields": [
    {
      "id": "<integer_field_id>",
      "value": 100
    },
    {
      "id": "<primary_field_id>",
      "value": "<record_id>"
    },
    {
      "id": "<primary_field2_id>",
      "value": {
        "id": "<record_id>"
      }
    },
    {
      "id": "<primary_record_field_id>",
      "value": {
        "name": "<record_name>"
      }
    },
    {
      "id": "<primary_contact_field_id>",
      "value": {
        "email": "<contact_email>"
      }
    },
    {
      "id": "<team_selector_field_id>",
      "value": {
        "email": "<team_email>"
      }
    },
    {
      "id": "<rating_field_id>",
      "value": 5
    },
    {
      "id": "<rating_field_id>",
      "value": {
        "id": "<rating_option_id>"
      }
    },
    {
      "name": "email_status",
      "value": {
        "id": "<option_id>"
      }
    },
    {
      "name": "email_status",
      "value": {
        "name": "Opted In"
      }
    },
    {
      "name": "text_field",
      "value": "text"
    },
    {
      "name": "dropdown_field",
      "value": {
        "id": "<option_id>"
      }
    },
    {
      "name": "dropdown_field",
      "value": {
        "name": "<option_name>"
      }
    },
    {
      "name": "dropdown_field2",
      "value": "<option_id>"
    }
  ],
  "unarchive": "prompt"
}

Single value fieldsMulti value fields

{
  "id": "<entity_record_id>",
  "fields": {
    "<email_field_id>": {
      "name": "email",
      "value": "[email protected]"
    },
    "<first_name_field_id>": {
      "name": "first_name_field_name",
      "value": "first name"
    },
    "<last_name_field_id>": {
      "name": "last_name_field_name",
      "value": "last name"
    },
    "<created_field_id>": {
      "name": "created",
      "value": "2020-01-30 01:00:00"
    },
    "<updated_field_id>": {
      "name": "updated",
      "value": "2020-01-30 01:00:00"
    }
  }
}

get

Get entity record by name or email

Authorizations

businessId & userId & apiKey

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

X-API-KEYstringRequired

Path parameters

object_identifierstringRequired

Query parameters

all_fieldsbooleanOptional

Return all fields.

field_idsstringOptional

Comma separated field ids to include in response. If present but empty, it will return default fields only.

field_namesstringOptional

Comma separated field names to include in response. If present but empty, it will return default fields only.

identifierstringRequired

Entity record name or contact email

Responses

200Success

application/json

get

/api/records/{object_identifier}/lookup

HTTPcURLJavaScriptPython

GET /api/records/{object_identifier}/lookup?identifier=text HTTP/1.1
Host: 
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
X-API-KEY: YOUR_API_KEY
Accept: */*

200Success

{
  "object_type": "string",
  "num_upcoming_activities": 0,
  "fields": {},
  "id": "18ff12e2-c4a0-4000-89e6-9b216dd9d801",
  "num_associated_team_members": 0,
  "client_info": {
    "num_addresses_v2": 0,
    "display_name": "string",
    "email_on_suppression_list": false
  },
  "access": {
    "view": true,
    "edit": true,
    "remove": true
  },
  "first_lead_source": {
    "id": "18ff12e2-c4a0-4000-8e84-0f8bb0dafb01",
    "type": "organic_search",
    "client": "18ff12e2-c4a0-4000-8dda-0175712cda01",
    "custom_object_record": "18ff12e2-c4a0-4000-831e-88c0810f2401",
    "source": "string",
    "campaign": "string",
    "medium": "string",
    "term": "string",
    "content": "string",
    "created": "1970-01-01T00:00:00.000Z",
    "_display": {
      "type": "string",
      "source": "string",
      "campaign": "string",
      "medium": "string",
      "term": "string",
      "content": "string"
    }
  },
  "last_lead_source": {
    "id": "18ff12e2-c4a0-4000-8fe9-71a84bc6c101",
    "type": "organic_search",
    "client": "18ff12e2-c4a0-4000-8803-a33e719dc801",
    "custom_object_record": "18ff12e2-c4a0-4000-8c84-44d6dd2b6f01",
    "source": "string",
    "campaign": "string",
    "medium": "string",
    "term": "string",
    "content": "string",
    "created": "1970-01-01T00:00:00.000Z",
    "_display": {
      "type": "string",
      "source": "string",
      "campaign": "string",
      "medium": "string",
      "term": "string",
      "content": "string"
    }
  },
  "lead_source_types": [
    {
      "value": "organic_search",
      "label": "string"
    }
  ]
}

post

Search entity records.

Authorizations

businessId & userId & apiKey

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

X-API-KEYstringRequired

Path parameters

object_identifierstringRequired

Query parameters

group_idstringOptional

Group id to filter records by.

in_group_idsstringOptional

Comma separated list of group ids. Only records in these groups will be returned. If both 'in_group_ids' and 'not_in_group_ids' are supplied, only 'in_group_ids' will be considered.

not_in_group_idsstringOptional

Comma separated list of group ids. Only records not in these groups will be returned. If both 'in_group_ids' and 'not_in_group_ids' are supplied, only 'in_group_ids' will be considered.

orderingstringOptional

Which field to use when ordering the results.

pageintegerOptional

A page number within the paginated result set.

page_sizeintegerOptional

Number of results to return per page.

searchstringOptional

A search term, by default, searches Contact's email, first_name, last_name, home_phone, mobile_phone, business_phone and Record's name. 'search_within_field_names' or 'search_within_field_ids' can be used to specify fields to search within.

Body

application/json

field_namesstring[] | nullableOptional

List of field names to return. Only one of 'field_names' or 'field_ids' is allowed.

field_idsstring · uuid[] | nullableOptional

List of field ids to return. Only one of 'field_ids' or 'field_names' is allowed.

search_within_field_namesstring[] | nullableOptional

List of field names to search within. Only one of 'search_within_field_names' or 'search_within_field_ids' is allowed.

search_within_field_idsstring · uuid[] | nullableOptional

List of field ids to search within. Only one of 'search_within_field_ids' or 'search_within_field_names' is allowed.

andboolean | nullableOptional

Whether to apply AND or OR logic in filters

Default: true

Responses

200Success

application/json

post

/api/records/{object_identifier}/search

HTTPcURLJavaScriptPython

POST /api/records/{object_identifier}/search HTTP/1.1
Host: 
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 266

{
  "field_names": [
    "text"
  ],
  "field_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "search_within_field_names": [
    "text"
  ],
  "search_within_field_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "query": [
    {
      "filters": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "and": true
    }
  ],
  "and": true
}

200Success

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "object_type": "text",
      "fields": {
        "id": {
          "id": "text",
          "field_type": "text",
          "display_name": "text",
          "value": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          }
        }
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "client_info": {
        "num_addresses_v2": 1,
        "display_name": "text",
        "email_on_suppression_list": true
      },
      "access": {
        "view": true,
        "edit": true,
        "remove": true
      }
    }
  ],
  "errors": [
    "error message"
  ]
}

post

Create or update entity record based on lookup criteria

Authorizations

businessId & userId & apiKey

X-BUSINESS-IDstringRequired

X-USER-IDstringRequired

X-API-KEYstringRequired

Path parameters

object_identifierstringRequired

Query parameters

return_all_fieldsbooleanOptional

If true, return all fields even if not updated

Body

application/json

lookup_valuestring · min: 1Required

Value to match the entity record (name for custom objects, email for contacts).

oncreate_unarchiveone of | nullableOptional

Behavior when creating and a matching archived record exists.

• prompt - prompt
• unarchive - unarchive
• overwrite - overwrite

string · enumOptional

• prompt - prompt
• unarchive - unarchive
• overwrite - overwrite

Possible values:

or

undefined · enumOptionalPossible values:

onupdate_archived_conflictone of | nullableOptional

Updates the identifier of matching archived record to not raise a conflict during update.

• overwrite - overwrite

string · enumOptional

• overwrite - overwrite

Possible values:

or

undefined · enumOptionalPossible values:

Responses

200Success

application/json

201Success

application/json

400Error

application/json

post

/api/records/{object_identifier}/upsert

HTTPcURLJavaScriptPython

POST /api/records/{object_identifier}/upsert HTTP/1.1
Host: 
X-BUSINESS-ID: YOUR_API_KEY
X-USER-ID: YOUR_API_KEY
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 189

{
  "lookup_value": "[email protected]",
  "fields": [
    {
      "name": "first_name",
      "value": "John"
    },
    {
      "name": "last_name",
      "value": "Doe"
    }
  ],
  "oncreate_unarchive": "prompt",
  "onupdate_archived_conflict": "overwrite"
}

Upsert contactUpsert custom record (rename example)

{
  "id": "<entity_record_id>",
  "action": "updated",
  "display_name": "Record Name",
  "fields": {
    "<field_id>": {
      "name": "field_name",
      "value": "field_value"
    }
  },
  "access": {
    "view": true,
    "edit": true,
    "remove": true
  }
}