Markit Docs

The Contacts resource allows you to retrieve contacts on your account and add new ones. The following actions can be performed on this resource:

Retrieve All Contacts
Retrieve a Single Contact
Add Contacts

Retrieve All Contacts

Retrieves all contacts on your account.

    GET https://api.markitai.com/v1/contacts

You can include additional parameters in the request as described in the Query Parameters section. For instance, the request below will return contacts with a status of "Subscribed".

    GET https://api.markitai.com/v1/contacts?status=Subscribed

Available query parameters:

limit: 20 (default)
offset: 0 (default)
status: ‘Subscribed’, ‘Unsubscribed’, ‘Invalid’, ‘Removed’ (default: 'All')
createdAt: ‘desc’ | ‘asc’ (default: ‘desc’)

Example Response:

{
  "data": [
    {
      "uid": "abc123",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "followType": "Profile",
      "followSourceType": "Desktop Webapp",
      "eventId": "",
      "complianceMessageSent": true,
      "complianceOptInOnMarkit": "2024-01-01T00:00:00.000Z",
      "spreadsheetData": {
        "fileId": "",
        "fileName": "",
        "status": "",
        "uploadFullName": ""
      },
      "phoneNumber": "+12345678910",
      "status": "Subscribed",
      "invalidErrorCode": 0,
      "messageFailureCount": 0,
      "membershipPlanId": "free",
      "membershipState": "Inactive",
      "membershipPromoCodeId": "",
      "discountEndDate": "",
      "groupOwnerPromoCodeId": "",
      "fullName": "John Doe",
      "profilePicURL": "https://firebasestorage.googleapis.com..."
    },
    {
      "uid": "123abc",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "followType": "Profile",
      "followSourceType": "Desktop Webapp",
      "eventId": "",
      "complianceMessageSent": true,
      "complianceOptInOnMarkit": "2024-01-01T00:00:00.000Z",
      "spreadsheetData": {
        "fileId": "",
        "fileName": "",
        "status": "",
        "uploadFullName": ""
      },
      "phoneNumber": "+19876543210",
      "status": "Unsubscribed",
      "invalidErrorCode": 0,
      "messageFailureCount": 0,
      "membershipPlanId": "free",
      "membershipState": "Inactive",
      "membershipPromoCodeId": "",
      "discountEndDate": "",
      "groupOwnerPromoCodeId": "",
      "fullName": "Mike",
      "profilePicURL": "https://firebasestorage.googleapis.com..."
    }
  ],
  "pagingData": {
    "prevPage": null,
    "currentPage": null,
    "nextPage": null,
    "currentPageString": null,
    "hasMore": false
  }
}

Retrieve a Single Contact

Retrieves a single contact with the contact ID equal to {id}.

    GET https://api.markitai.com/v1/contacts/{id}

Example Response:

{
  "follower": {
    "uid": "abc123",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "followType": "Profile",
    "followSourceType": "Desktop Webapp",
    "eventId": "",
    "complianceMessageSent": true,
    "complianceOptInOnMarkit": "2024-01-01T00:00:00.000Z",
    "spreadsheetData": {
      "fileId": "",
      "fileName": "",
      "status": "",
      "uploadFullName": ""
    },
    "phoneNumber": "+12345678910",
    "status": "Subscribed",
    "invalidErrorCode": 0,
    "messageFailureCount": 0,
    "membershipPlanId": "free",
    "membershipState": "Inactive",
    "membershipPromoCodeId": "",
    "discountEndDate": "",
    "groupOwnerPromoCodeId": "",
    "fullName": "John Doe",
    "profilePicURL": "https://firebasestorage.googleapis.com…",
    "formResponses": [
        {
          "id": "111111",
          "questionId": "222222",
          "lastResponded": "2024-01-01T00:00:00.000Z",
          "eventId": "123123",
          "responses": ["john@gmail.com"]
        },
        ...
    ]
  }
}

Adds up to 20,000 contacts to your audience in one request (the body can be up to 10 MB). A request with 25 contacts or fewer is added right away and returns what happened to each contact. A request with more than 25 is started as a background import, the same as importing a file in Markit. Adding contacts here never sends a text. To subscribe one person the way your profile does, which triggers your Clicked Subscribe automation, use Subscribe to User instead.

    POST https://api.markitai.com/v1/contacts

Consent. You are responsible for having explicit opt-in consent from every person you add before you send their phone numbers to Markit, as described in section 7.9 of the Terms of Use. That includes keeping your own record of when, and how, each person gave consent. Markit doesn't ask for or store proof of consent when you call this endpoint.

Parameter	Type	Required	Default	Description
`contacts`	array	Yes	-	1 to 20,000 contacts. Each has the fields in the table below.
`listId`	string	No	-	Also put the contacts on this audience list. The list must be on your account.
`importName`	string	No	Added with API	The name an import is saved under in your import history. Only used when more than 25 contacts are sent.
`updateExistingContacts`	boolean	No	false	Also save `formAnswers` for contacts who are already subscribed, replacing their earlier answer to each of those questions. Nothing else about them changes. Contacts who unsubscribed or were removed are never updated this way.

Each item in contacts:

Parameter	Type	Required	Description
`fullName`	string	Yes	The contact's full name.
`phoneNumber`	string	Yes	The phone number, in any common format. Only US numbers can receive texts. See Phone Number Formatting.
`formAnswers`	object	No	Answers to your saved questions, as `{ "questionId": ["answer"] }`. Saved for contacts who are newly added or added again. People who are already subscribed keep their answers unless you set `updateExistingContacts` to true. For a choice question, each answer must be one of its options.

With updateExistingContacts, a contact who is already subscribed comes back as already_subscribed with answersUpdated set to true (or false if they had no answers or saving failed). In an import, existing contacts with answers are updated in the background and counted in toUpdate. They don't count toward your limit of 500 imported contacts.

Contacts who unsubscribed themselves are never added again. A contact who was removed is added again. When more than 25 contacts are sent, an import stores one answer per question, so a request with several answers to one question must have 25 contacts or fewer.

A request of more than 25 contacts is an import, which needs the Pro plan or higher, the same as importing in Markit. Requests of 25 or fewer work on any plan. An account can also import 500 contacts in total unless Markit has approved it for more, the same limit as the import in Markit. Contacts added in requests of 25 or fewer don't count toward it.

Example Request

{
  "listId": "list123",
  "contacts": [
    {
      "fullName": "Sam Rivera",
      "phoneNumber": "+14155550123",
      "formAnswers": { "question1_id": ["Creator"] }
    },
    { "fullName": "Alex Kim", "phoneNumber": "(415) 555-0124" }
  ]
}

Example Responses:

25 contacts or fewer. Each contact gets one outcome: added, re_added, already_subscribed, opted_out, invalid_number, excluded, duplicate or failed (safe to try again).

{
  "status": "done",
  "counts": { "added": 1, "already_subscribed": 1 },
  "results": [
    {
      "phoneNumber": "+14155550123",
      "fullName": "Sam Rivera",
      "outcome": "added",
      "contactId": "abc123",
      "reason": null
    },
    {
      "phoneNumber": "+14155550124",
      "fullName": null,
      "outcome": "already_subscribed",
      "contactId": "def456",
      "reason": "Already subscribed."
    }
  ],
  "list": { "id": "list123", "contactsAdded": 2 }
}

More than 25 contacts, responding with status 202. The import runs in the background and shows in your import history in Markit. results lists the contacts that were skipped (up to 50) and why.

{
  "status": "import_started",
  "importId": "xyz789",
  "fileName": "Added with API",
  "toImport": 940,
  "counts": { "to_add": 940, "to_re_add": 0, "already_subscribed": 55, "invalid_number": 5 },
  "results": [ ... ],
  "message": "Import started: 940 contacts are being added in the background. ..."
}

Errors use the same format as the rest of the API, { "error", "code", "message" }, and nothing is added when a request is refused:

Status	`code`	When
400	`MISSING_FIELDS`	`contacts` is missing or empty.
400	`TOO_MANY_CONTACTS`	More than 20,000 contacts.
400	`INVALID_CONTACTS`	A contact has no name or number, or `formAnswers` isn't an object of arrays. `details` lists which.
400	`INVALID_FORM_QUESTION_IDS`	A question id isn't one of your saved questions. `details` lists them.
400	`INVALID_FORM_ANSWERS`	An answer to a choice question isn't one of its options. `details` lists which.
400	`MULTIPLE_ANSWERS_NOT_SUPPORTED`	More than 25 contacts and one has several answers to a question.
403	`PRO_PLAN_REQUIRED`	More than 25 contacts were sent and the account isn't on the Pro plan or higher. Checked first.
403	`IMPORT_LIMIT_REACHED`	The import would pass your limit of 500 imported contacts.
404	`LIST_NOT_FOUND`	`listId` isn't a list on your account.

Contacts

Retrieve All Contacts

Retrieve a Single Contact

Add Contacts

On this page