Contacts

Get all contacts

get

/contacts

Returns a paginated list of contacts for the organization.

Rate limit: 300 requests per minute

Authorizations

AuthorizationstringRequired

Authorization: Bearer

Query parameters

cursorstringOptional

The cursor to use for pagination.

limitinteger · int64Optional

The number of contacts to fetch. Defaults to 100. Must be greater than 0 and less than 1000.

Responses

200Success

application/json

request_idstringOptional

The request ID for tracking.

400

The request was invalid or could not be completed.

application/json

403

The authenticated caller or organization is not allowed to access this endpoint or operation.

application/json

404Error

application/json

500

An unexpected internal error occurred.

application/json

get/contacts

GET /contacts HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "account": {
        "external_ids": [
          {
            "external_id": "text",
            "label": "text"
          }
        ],
        "id": "text"
      },
      "avatar_url": "text",
      "custom_fields": {
        "role": {
          "value": "admin"
        }
      },
      "email": "text",
      "emails": [
        "text"
      ],
      "external_ids": [
        {
          "external_id": "text",
          "label": "text"
        }
      ],
      "id": "text",
      "integration_user_ids": [
        {
          "id": "text",
          "source": "text"
        }
      ],
      "name": "text",
      "phone_numbers": [
        "text"
      ],
      "portal_role": "no_access",
      "portal_role_id": "text",
      "primary_phone_number": "text"
    }
  ],
  "pagination": {
    "cursor": "text",
    "has_next_page": true
  },
  "request_id": "text"
}

Create a new contact

post

/contacts

Creates a new contact with the specified email and optional metadata.

Rate limit: 300 requests per minute

Authorizations

AuthorizationstringRequired

Authorization: Bearer

Body

account_external_idstringOptional

The external ID of the account that this contact belongs to. Cannot be used together with account_id.

account_idstringOptional

The account that this contact belongs to.

avatar_urlstringOptional

The avatar URL of the contact. Must be a square .png, .jpg or .jpeg.

emailstringOptional

The email of the contact.

namestringRequired

The name of the contact.

phone_numbersstring[]Optional

The phone numbers of the contact. Must contain only digits 0-9 and be 15 digits or less.

portal_rolestring · enumOptional

The portal role to assign to the contact. If not provided uses the default portal role from the portal settings.

Possible values:

portal_role_idstringOptional

The ID of the custom portal role to assign to the contact. Takes precedence over portal_role if provided.

primary_phone_numberstringOptional

The primary phone number. Must be in the list of phone_numbers. If there are any phone_numbers and this is not specified, the first phone number will be primary.

Responses

200Success

application/json

request_idstringOptional

The request ID for tracking.

400

The request was invalid or could not be completed.

application/json

403

The authenticated caller or organization is not allowed to access this endpoint or operation.

application/json

404Error

application/json

500

An unexpected internal error occurred.

application/json

post/contacts

POST /contacts HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 326

{
  "account_external_id": "text",
  "account_id": "text",
  "avatar_url": "text",
  "custom_fields": [
    {
      "slug": "text",
      "value": "text",
      "values": [
        "text"
      ]
    }
  ],
  "email": "text",
  "external_ids": [
    {
      "external_id": "text",
      "label": "text"
    }
  ],
  "name": "text",
  "phone_numbers": [
    "text"
  ],
  "portal_role": "no_access",
  "portal_role_id": "text",
  "primary_phone_number": "text"
}

{
  "data": {
    "account": {
      "external_ids": [
        {
          "external_id": "text",
          "label": "text"
        }
      ],
      "id": "text"
    },
    "avatar_url": "text",
    "custom_fields": {
      "role": {
        "value": "admin"
      }
    },
    "email": "text",
    "emails": [
      "text"
    ],
    "external_ids": [
      {
        "external_id": "text",
        "label": "text"
      }
    ],
    "id": "text",
    "integration_user_ids": [
      {
        "id": "text",
        "source": "text"
      }
    ],
    "name": "text",
    "phone_numbers": [
      "text"
    ],
    "portal_role": "no_access",
    "portal_role_id": "text",
    "primary_phone_number": "text"
  },
  "request_id": "text"
}

Get a contact by its ID or external ID

get

/contacts/{id}

Returns a single contact by ID or external ID.

Rate limit: 300 requests per minute

Authorizations

AuthorizationstringRequired

Authorization: Bearer

Path parameters

idstringRequired

The ID or external ID of the contact.

Responses

200Success

application/json

request_idstringOptional

The request ID for tracking.

400

The request was invalid or could not be completed.

application/json

403

The authenticated caller or organization is not allowed to access this endpoint or operation.

application/json

404Error

application/json

500

An unexpected internal error occurred.

application/json

get/contacts/{id}

GET /contacts/{id} HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "account": {
      "external_ids": [
        {
          "external_id": "text",
          "label": "text"
        }
      ],
      "id": "text"
    },
    "avatar_url": "text",
    "custom_fields": {
      "role": {
        "value": "admin"
      }
    },
    "email": "text",
    "emails": [
      "text"
    ],
    "external_ids": [
      {
        "external_id": "text",
        "label": "text"
      }
    ],
    "id": "text",
    "integration_user_ids": [
      {
        "id": "text",
        "source": "text"
      }
    ],
    "name": "text",
    "phone_numbers": [
      "text"
    ],
    "portal_role": "no_access",
    "portal_role_id": "text",
    "primary_phone_number": "text"
  },
  "request_id": "text"
}

Update a contact by its ID or external ID

patch

/contacts/{id}

Updates a contact by ID or external ID. Only provided fields are modified.

Rate limit: 300 requests per minute

Authorizations

AuthorizationstringRequired

Authorization: Bearer

Path parameters

idstringRequired

The ID or external ID of the contact to update.

Body

account_external_idstringOptional

The external ID of the account to move the contact to. Cannot be used together with account_id.

account_idstringOptional

The account to move the contact to. If empty string is passed in, the contact will be removed from its account.

avatar_urlstringOptional

The avatar URL of the contact. Must be a square .png, .jpg or .jpeg.

emailstringOptional

The email of the contact. Cannot be used together with the emails array field.

namestringOptional

in: body The name of the contact.

phone_numbersstring[]Optional

The phone numbers of the contact. Must contain only digits 0-9 and be 15 digits or less.

portal_rolestring · enumOptional

The portal role to assign to the contact. Can be one of no_access, member, or admin, or a custom role slug.

Possible values:

portal_role_idstringOptional

The ID of the custom portal role to assign to the contact. Takes precedence over portal_role if provided.

primary_phone_numberstringOptional

The primary phone number. Must be in the list of phone_numbers. If there are any phone_numbers and this is not specified, the first phone number will be primary.

Responses

200Success

application/json

request_idstringOptional

The request ID for tracking.

400

The request was invalid or could not be completed.

application/json

403

The authenticated caller or organization is not allowed to access this endpoint or operation.

application/json

404Error

application/json

500

An unexpected internal error occurred.

application/json

patch/contacts/{id}

PATCH /contacts/{id} HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 372

{
  "account_external_id": "text",
  "account_id": "text",
  "avatar_url": "text",
  "custom_fields": [
    {
      "slug": "text",
      "value": "text",
      "values": [
        "text"
      ]
    }
  ],
  "email": "text",
  "emails": [
    {
      "email": "text",
      "is_primary": true
    }
  ],
  "external_ids": [
    {
      "external_id": "text",
      "label": "text"
    }
  ],
  "name": "text",
  "phone_numbers": [
    "text"
  ],
  "portal_role": "no_access",
  "portal_role_id": "text",
  "primary_phone_number": "text"
}

{
  "data": {
    "account": {
      "external_ids": [
        {
          "external_id": "text",
          "label": "text"
        }
      ],
      "id": "text"
    },
    "avatar_url": "text",
    "custom_fields": {
      "role": {
        "value": "admin"
      }
    },
    "email": "text",
    "emails": [
      "text"
    ],
    "external_ids": [
      {
        "external_id": "text",
        "label": "text"
      }
    ],
    "id": "text",
    "integration_user_ids": [
      {
        "id": "text",
        "source": "text"
      }
    ],
    "name": "text",
    "phone_numbers": [
      "text"
    ],
    "portal_role": "no_access",
    "portal_role_id": "text",
    "primary_phone_number": "text"
  },
  "request_id": "text"
}

Delete a contact by its ID or external ID

delete

/contacts/{id}

Permanently deletes a contact by ID or external ID.

Rate limit: 30 requests per minute

Authorizations

AuthorizationstringRequired

Authorization: Bearer

Path parameters

idstringRequired

The ID or external ID of the contact to delete.

Responses

200Success

application/json

request_idstringOptional

The request ID for tracking.

403

The authenticated caller or organization is not allowed to access this endpoint or operation.

application/json

delete/contacts/{id}

DELETE /contacts/{id} HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "request_id": "text"
}

Search for contacts by a given filter

post

/contacts/search

Filterable fields and their allowed operators:

Field	Allowed operators
id	equals, in, not_in
email	equals, in, not_in, string_contains
name	equals, in, not_in, string_contains
account_id	equals, in, not_in

For custom fields, pass the field slug as field.

Rate limit: 120 requests per minute

Authorizations

AuthorizationstringRequired

Authorization: Bearer

Body

cursorstringOptional

The cursor to use for pagination.

limitinteger · int64Optional

The number of contacts to fetch. Defaults to 100. Must be greater than 0 and less than 1000.

search_textstringOptional

Fuzzy text search. Results are intersected with any provided filter.

Responses

200Success

application/json

request_idstringOptional

The request ID for tracking.

403

The authenticated caller or organization is not allowed to access this endpoint or operation.

application/json

post/contacts/search

POST /contacts/search HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 194

{
  "cursor": "text",
  "filter": {
    "field": "text",
    "operator": "equals",
    "subfilters": [
      {
        "field": "state",
        "operator": "equals",
        "value": "new"
      }
    ],
    "value": "text",
    "values": [
      "text"
    ]
  },
  "limit": 1,
  "search_text": "text"
}

{
  "data": [
    {
      "account": {
        "external_ids": [
          {
            "external_id": "text",
            "label": "text"
          }
        ],
        "id": "text"
      },
      "avatar_url": "text",
      "custom_fields": {
        "role": {
          "value": "admin"
        }
      },
      "email": "text",
      "emails": [
        "text"
      ],
      "external_ids": [
        {
          "external_id": "text",
          "label": "text"
        }
      ],
      "id": "text",
      "integration_user_ids": [
        {
          "id": "text",
          "source": "text"
        }
      ],
      "name": "text",
      "phone_numbers": [
        "text"
      ],
      "portal_role": "no_access",
      "portal_role_id": "text",
      "primary_phone_number": "text"
    }
  ],
  "pagination": {
    "cursor": "text",
    "has_next_page": true
  },
  "request_id": "text"
}