Getting people

You can retrieve people from Autopilot using the /v1/person/get endpoint.

Retrieving contacts

Here is a cURL request to get the first page of contacts:

curl --request POST \
  --url https://api.ap3api.com/v1/person/get \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: X-API-KEY' \
  --data '{
	"limit": 100,
	"sort_order": "desc",
	"sort_by_field_id": null,
	"offset": 0,
	"fields": ["str::first", "str::last", "str::email"],
	"q": ""
}'

The payload values are as followed:

Key Possible values Description

limit

1-100

The number of people to be returned.

sort_order

asc, desc

The order to sort by, based on sort_by_field_id. Only relevant if sort_by_field_id is provided. Default desc.

sort_by_field_id

(any field, e.g. str::email)

The field to sort by, default is 'c' which is the "Create at" for this contact.

offset

0-10000000

The offset for fetching subsequent pages of contacts, default 0.

cursor_id

(a UUID, e.g. 00609c898a4490c5800a5453)

When retrieving subsequent pages of contacts, provide the cursor_id returned in the previous request.

fields

(an array of field_ids)

A list of the field IDs you want returned in the payload, see list below.

q

(a valid search string)

A simple text search for contacts.

A list of person fields

Use any of these fields in the "fields" array in your request, to have them included in the payload response.

Field name field_id

Email

str::email

External ID

str::ei

First

str::first

Last

str::last

Phone

phn::phone

GDPR

bol::gdpr

Birthday

dtz::b

Postal

str::postal

Country

geo::country

Region

geo::region

City

geo::city

You can also request custom fields which follow this format:

Field component Examples Description

Type

int:cm:my-custom-integer

The first part of the field is the type. Autopilot is strongly typed so the type is critical and the data sent to the API must be of a valid type.

Namespace

cm:custom-variable

The second part of the field is the namespace. This is used internally in Autopilot to delineate data coming from different data sources. "cm" stands for custom, which is custom fields that you add to your Autopilot account.

Name

str:cm: custom-variable

The name of the field itself. This will be stripped of any special characters and use hyphens instead of spaces.

The response will be something like the following, in this example we only requested 2 contacts so the response payload isn’t too large. In reality, you can retrieve up to 100 contacts per payload:

{
  "contacts": [
    {
      "id": "00609c86fc4490c5800a0600",
      "fields": {
        "idt::o": "10609c87424490c5800a1501",
        "str::email": "chris.smith@example.com",
        "str::first": "Chris",
        "str::last": "Smith"
      }
    },
    {
      "id": "00609c85b8b2bdea4cb6e001",
      "fields": {
        "idt::o": "10609c86414490c58009e200",
        "str::email": "alex.smith@example.com",
        "str::first": "Alex",
        "str::last": "Smith"
      }
    }
  ],
  "meta": {
    "total_contacts": 3193,
    "total_organizations": 0,
    "total_matches": 3193,
    "total_subscribers": 3107
  },
  "offset": 0,
  "next_offset": 3,
  "cursor_id": "00609c898a4490c5800a5453",
  "has_more": true
}

The payload items are as follows:

Key Description

contacts

An array of contacts with an id and a fields hash which contacts the list of fields you requested to be returned. Note that if a contact has an associated organization it will include a idt::o field, which is the ID of the organization with which this contact is associated.

meta

A hash of meta data containing information about the matches to your contacts GET request, including:

  • total_contacts - Number of people in your database in total

  • total_organizations - Number of organizations in your database in total

  • total_matches - Number of people matching your query or filter

  • total_subscribers - Number of contacts in your database who are subscribed to receive email marketing

offset

The offset which was set on this request.

next_offset

The offset for fetching the next page of contacts.

cursor_id

When retrieving the next page of contacts, provide this cursor_id.

has_more

Whether or not there is a next page of contacts.

Retrieving the next page of contacts

If we retrieve the first page of contacts like so:

curl --request POST \
  --url https://api.ap3api.com/v1/person/get \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: X-API-KEY' \
  --data '{
	"limit": 50,
}'

The response is:

{
   "contacts":[
      {
         "id":"00609c9e644490c5800da401",
         "fields":{
            "idt::o":"10609c9eba4490c5800dad00"
         }
      },
      {
         "id":"00609c9db64490c5800d9900",
         "fields":{
            "idt::o":"10609c9ddbb2bdea4cbc3601"
         }
      },
      {
         "id":"00609c9cf04490c5800d6101",
         "fields":{
            "idt::o":"10609c9d1bb2bdea4cbbf900"
         }
      },
      {
         "id":"00609c9a34b2bdea4cbb4300",
         "fields":{
            "idt::o":"10609c9b9d4490c5800d5701"
         }
      },
      {
         "id":"00609c96254490c5800cc101"
      },
      {
         "id":"00609c93d34490c5800c5400",
         "fields":{
            "idt::o":"10609c93d34490c5800c5700"
         }
      },
      {
         "id":"00609c934bb2bdea4cba2d01",
         "fields":{
            "idt::o":"10609c93a64490c5800c4e00"
         }
      },
      {
         "id":"00609c8f71b2bdea4cb8af00",
         "fields":{
            "idt::o":"10609c8fa24490c5800b8c01"
         }
      },
      {
         "id":"00609c8f1f4490c5800b7401",
         "fields":{
            "idt::o":"10609c8f594490c5800b8300"
         }
      },
      {
         "id":"00609c8e5e4490c5800b5300"
      },
      {
         "id":"00609c89df4490c5800a6c01",
         "fields":{
            "idt::o":"10609c8a25b2bdea4cb7e500"
         }
      },
      {
         "id":"00609c86fc4490c5800a0600",
         "fields":{
            "idt::o":"10609c87424490c5800a1501"
         }
      },
      {
         "id":"00609c85b8b2bdea4cb6e001",
         "fields":{
            "idt::o":"10609c86414490c58009e200"
         }
      },
      {
         "id":"00609c7db2a9b4c251966500"
      },
      {
         "id":"00609c7bc34490c580075f01",
         "fields":{
            "idt::o":"10609c7c15a9b4c25195ee00"
         }
      },
      {
         "id":"00609c7b5da9b4c25195c800"
      },
      {
         "id":"00609c75f94490c580064001",
         "fields":{
            "idt::o":"10609c761f4490c580064900"
         }
      },
      {
         "id":"00609c6824c536dc9bbf3200",
         "fields":{
            "idt::o":"10609c6908c536dc9bbf5d01"
         }
      },
      {
         "id":"00609c67ab241bfc04733901",
         "fields":{
            "idt::o":"10609c67ab241bfc04733c01"
         }
      },
      {
         "id":"00609c672cc536dc9bbefd00",
         "fields":{
            "idt::o":"10609c6776241bfc04732d01"
         }
      },
      {
         "id":"00609c6683241bfc0472fc01"
      },
      {
         "id":"00609c65b0c536dc9bbead00",
         "fields":{
            "idt::o":"10609c65b0c536dc9bbeb000"
         }
      },
      {
         "id":"00609c6586c536dc9bbe9b01",
         "fields":{
            "idt::o":"10609c6586c536dc9bbe9e01"
         }
      },
      {
         "id":"00609c5b40241bfc046ef200",
         "fields":{
            "idt::o":"10609c5b5b241bfc046f0101"
         }
      },
      {
         "id":"00609c5825241bfc046e6c01",
         "fields":{
            "idt::o":"10609c5884c536dc9bbbb800"
         }
      },
      {
         "id":"00609c50a5c536dc9bba9300"
      },
      {
         "id":"00609c4df8241bfc046c8701",
         "fields":{
            "idt::o":"10609c4e12c536dc9bb9f700"
         }
      },
      {
         "id":"00609c4d20c536dc9bb9e700"
      },
      {
         "id":"00609c4b9d241bfc046bc300",
         "fields":{
            "idt::o":"10609c4bd5241bfc046be000"
         }
      },
      {
         "id":"00609c4aafc536dc9bb9db01"
      },
      {
         "id":"00609c4aac241bfc046b7c01",
         "fields":{
            "idt::o":"10609c4b22241bfc046b9c00"
         }
      },
      {
         "id":"00609c46c1241bfc046b3f00",
         "fields":{
            "idt::o":"10609c470ac536dc9bb90e01"
         }
      },
      {
         "id":"00609c460dc536dc9bb8ce01",
         "fields":{
            "idt::o":"10609c4632241bfc046b3900"
         }
      },
      {
         "id":"00609c45a2241bfc046b3100",
         "fields":{
            "idt::o":"10609c45b9c536dc9bb8c201"
         }
      },
      {
         "id":"00609c3efb241bfc046a6f01"
      },
      {
         "id":"00609c3d01c536dc9bb76e00",
         "fields":{
            "idt::o":"10609c3d30c536dc9bb77101"
         }
      },
      {
         "id":"00609c3a7d241bfc04682c01",
         "fields":{
            "idt::o":"10609c3a8f241bfc04683501"
         }
      },
      {
         "id":"00609c3a63c536dc9bb75900",
         "fields":{
            "idt::o":"10609c3aa0241bfc04684100"
         }
      },
      {
         "id":"00609c38f8241bfc0467f901"
      },
      {
         "id":"00609c376dc536dc9bb70500",
         "fields":{
            "idt::o":"10609c37d9241bfc0467c901"
         }
      },
      {
         "id":"00609c3752c536dc9bb6ff01",
         "fields":{
            "idt::o":"10609c37d7241bfc0467c601"
         }
      },
      {
         "id":"00609c2f74c536dc9bb53700",
         "fields":{
            "idt::o":"10609c2f9bc536dc9bb53d01"
         }
      },
      {
         "id":"00609c2d3e241bfc04663601",
         "fields":{
            "idt::o":"10609c3085241bfc04671e01"
         }
      },
      {
         "id":"00609c2addc536dc9bb4a100"
      },
      {
         "id":"00609c265d241bfc04646e01",
         "fields":{
            "idt::o":"10609c266c241bfc04647700"
         }
      },
      {
         "id":"00609c2460241bfc0463f300"
      },
      {
         "id":"00609c2321c536dc9bb42100",
         "fields":{
            "idt::o":"10609c23a0c536dc9bb43600"
         }
      },
      {
         "id":"00609c2136241bfc04631a01",
         "fields":{
            "idt::o":"10609c2164c536dc9bb3e100"
         }
      },
      {
         "id":"00609c2128241bfc04631101",
         "fields":{
            "idt::o":"10609c2149c536dc9bb3da00"
         }
      },
      {
         "id":"00609c1f7c241bfc0462ce00"
      }
   ],
   "meta":{
      "total_contacts":3204,
      "total_organizations":0,
      "total_matches":3204,
      "total_subscribers":3118
   },
   "offset":0,
   "next_offset":50,
   "cursor_id":"00609ca2444490c5800e0605",
   "has_more":true
}

We retrieve the second page of contacts like this:

curl --request POST \
  --url http://localhost:8100/v1/person/get \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: X-API-KEY' \
  --data '{
	"limit": 50,
        "offset": 50,
        "cursor_id": "00609ca377b2bdea4cbd4645"
}'

And then we receive the next 50 contacts with the offset, next_offset and cursor_id updated:

{
   "contacts":[
      {
         "id":"00609c1f7c241bfc0462ce00"
      },
      {
         "id":"00609c1e70241bfc04600501"
      },
      {
         "id":"00609c1d30241bfc045fe100",
         "fields":{
            "idt::o":"10609c1dcec536dc9bb35001"
         }
      },
      {
         "id":"00609c1cf2241bfc045fda01",
         "fields":{
            "idt::o":"10609c1ec6241bfc0462a800"
         }
      },
      {
         "id":"00609c18ac241bfc045f3600"
      },
      {
         "id":"00609c15f9241bfc04422b01",
         "fields":{
            "idt::o":"10609c16f9241bfc0442b200"
         }
      },
      {
         "id":"00609c065a241bfc04402100",
         "fields":{
            "idt::o":"10609c06a9c536dc9baec701"
         }
      },
      {
         "id":"00609c0527c536dc9badc001",
         "fields":{
            "idt::o":"10609c054e241bfc04401700"
         }
      },
      {
         "id":"00609c0476c536dc9bad8100"
      },
      {
         "id":"00609c041a241bfc04400901"
      },
      {
         "id":"00609c038b241bfc043ffe00",
         "fields":{
            "idt::o":"10609c03e9c536dc9bad4901"
         }
      },
      {
         "id":"00609c01eb241bfc043fe701",
         "fields":{
            "idt::o":"10609c01fb241bfc043ff000"
         }
      },
      {
         "id":"00609bfe80241bfc043f7a00",
         "fields":{
            "idt::o":"10609bfec0241bfc043f7f01"
         }
      },
      {
         "id":"00609bf9f5241bfc043eb301",
         "fields":{
            "idt::o":"10609bfa56241bfc043ebc00"
         }
      },
      {
         "id":"00609bf875c536dc9baaa300",
         "fields":{
            "idt::o":"1060992abdf990e1f935da01"
         }
      },
      {
         "id":"00609bf6ad241bfc043d8001",
         "fields":{
            "idt::o":"10609bf6e2c536dc9ba9d000"
         }
      },
      {
         "id":"00609bf41ac536dc9ba98b00",
         "fields":{
            "idt::o":"10609bf7f3241bfc043dec00"
         }
      },
      {
         "id":"00609bf401c536dc9ba97f01",
         "fields":{
            "idt::o":"10609bf494c536dc9ba9a301"
         }
      },
      {
         "id":"00609bf3b4241bfc043cc300",
         "fields":{
            "idt::o":"10609bf3b4241bfc043cc600"
         }
      },
      {
         "id":"00609bf295c536dc9ba90a01",
         "fields":{
            "idt::o":"10609bf2a5241bfc043cb200"
         }
      },
      {
         "id":"00609bf25b241bfc043cac00",
         "fields":{
            "idt::o":"10609bf2be241bfc043cb500"
         }
      },
      {
         "id":"00609bf04bc536dc9ba8a001"
      },
      {
         "id":"00609bef37c536dc9ba86700",
         "fields":{
            "idt::o":"10609bf076241bfc043c6b00"
         }
      },
      {
         "id":"00609beefe241bfc043c1901",
         "fields":{
            "idt::o":"10609bef48241bfc043c2a00"
         }
      },
      {
         "id":"00609beea3241bfc04369a00",
         "fields":{
            "idt::o":"10609beed0241bfc0436a001"
         }
      },
      {
         "id":"00609bee5bc536dc9ba81101"
      },
      {
         "id":"00609bee04c536dc9ba7f000",
         "fields":{
            "idt::o":"10609bee18241bfc04369400"
         }
      },
      {
         "id":"00609bedbac536dc9ba7c601",
         "fields":{
            "idt::o":"10609bedfdc536dc9ba7ea00"
         }
      },
      {
         "id":"00609bed11c536dc9ba79c00"
      },
      {
         "id":"00609bebd8241bfc04368801"
      },
      {
         "id":"00609beaecc536dc9ba6c100"
      },
      {
         "id":"00609be513c536dc9ba57b01"
      },
      {
         "id":"00609be4ebc536dc9ba56600",
         "fields":{
            "idt::o":"10609be55bc536dc9ba58c00"
         }
      },
      {
         "id":"00609be37b241bfc04353c01",
         "fields":{
            "idt::o":"106080b9775f7b1b2c7efa00"
         }
      },
      {
         "id":"00609be073241bfc0434f300",
         "fields":{
            "idt::o":"10609be092241bfc0434f601"
         }
      },
      {
         "id":"00609bde31241bfc0434ca01",
         "fields":{
            "idt::o":"10609bde4d241bfc0434cd00"
         }
      },
      {
         "id":"00609bdb10c536dc9b9f7d00",
         "fields":{
            "idt::o":"10609bddbbc536dc9ba3da01"
         }
      },
      {
         "id":"00609bda97241bfc04347e01",
         "fields":{
            "idt::o":"10609bdabb241bfc04348500"
         }
      },
      {
         "id":"00609bd771c536dc9b9eaa00",
         "fields":{
            "idt::o":"10609bd7a5c536dc9b9eb601"
         }
      },
      {
         "id":"00609bd70ec536dc9b9e9a01"
      },
      {
         "id":"00609bd21ac536dc9b9d4f00",
         "fields":{
            "idt::o":"10609bd288241bfc0433c201"
         }
      },
      {
         "id":"00609bcecac536dc9b9cc401"
      },
      {
         "id":"00609bcab5241bfc0432a900",
         "fields":{
            "idt::o":"10609bcb00c536dc9b9c1401"
         }
      },
      {
         "id":"00609bca6d241bfc04329701"
      },
      {
         "id":"00609bc917c536dc9b9bda00"
      },
      {
         "id":"00609bc5c0c536dc9b99c801",
         "fields":{
            "idt::o":"10609bc610c536dc9b99cf00"
         }
      },
      {
         "id":"00609bc598241bfc04317e00",
         "fields":{
            "idt::o":"10609bc598241bfc04318100"
         }
      },
      {
         "id":"00609bc577241bfc04317501",
         "fields":{
            "idt::o":"10609bc577241bfc04317801"
         }
      },
      {
         "id":"00609bc4dac536dc9b99b300"
      },
      {
         "id":"00609bc41b241bfc04312d01"
      }
   ],
   "meta":{
      "total_contacts":3205,
      "total_organizations":0,
      "total_matches":3205,
      "total_subscribers":3119
   },
   "offset":50,
   "next_offset":100,
   "cursor_id":"00609ca377b2bdea4cbd4645",
   "has_more":true
}