---
title: "Import a new contact"
method: POST
path: "/import/contacts"
tags: ["import"]
---

# Import a new contact

`POST /import/contacts`

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

**Rate limit:** 20 requests per minute

## Request body

- ImportContactRequestBody
  - `account_id` string — The account that this contact belongs to.
  - `avatar_url` string — The avatar URL of the contact. Must be a square .png, .jpg or .jpeg.
  - `custom_fields` CustomFieldValue[] — An array of custom fields to be applied to this contact.
    - `slug` string — The slug of the custom field.
    - `value` string — The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID.
    - `values` string[] — The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint.
  - `email` string, required — The email of the contact.
  - `name` string, required — The name of the contact.
  - `phone_numbers` string[] — The phone numbers of the contact. Must contain only digits 0-9 and be 15 digits or less.
  - `portal_role` 'no_access' | 'member' | 'admin' — The portal role to assign to the contact. If not provided uses the default portal role from the portal settings.
  - `primary_phone_number` string — 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.

## Response `200`

- ImportContactResponseBody
  - `data` Contact
    - `account` MiniAccount
      - `external_ids` ExternalID[] — External IDs associated with the account.
        - `external_id` string — The external ID. Must be unique per object type (ex. account).
        - `label` string — The label of the external ID. Must be unique per object.
      - `id` string — The ID of the account.
    - `avatar_url` string — Avatar URL of the contact.
    - `custom_fields` object — Custom field values associated with the issue.
    - `email` string — The primary email of the contact, if it exists.
    - `emails` string[] — The list of all emails of the contact.
    - `external_ids` ExternalID[] — External IDs associated with the contact.
      - `external_id` string — The external ID. Must be unique per object type (ex. account).
      - `label` string — The label of the external ID. Must be unique per object.
    - `id` string — The ID of the contact.
    - `integration_user_ids` IntegrationUserID[] — Integration user IDs linking this contact to external systems.
      - `id` string — The user ID in the external system.
      - `source` string — The integration source (e.g., "slack", "intercom", "hubspot").
    - `name` string — The name of the contact.
    - `phone_numbers` string[] — The list of all phone numbers of the contact.
    - `portal_role` 'no_access' | 'member' | 'admin' — Portal role slug assigned to the contact. For backwards compatibility.
    - `portal_role_id` string — The ID of the custom portal role assigned to the contact.
    - `primary_phone_number` string — The primary phone number of the contact, if it exists.
  - `request_id` string — The request ID for tracking.

## Other responses

- `400` — The request was invalid or could not be completed.
- `404`
- `500` — An unexpected internal error occurred.

---

[API](https://skmtc.net/usepylon/apis/pylon-api.md) · [All operations](https://skmtc.net/usepylon/apis/pylon-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usepylon/pylon-api/versions/484a11d5ddb2/schema)