Create Contact | Calendly | Developer Documentation

const url = 'https://api.calendly.com/contacts';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"Jane Doe","emails":[{"email":"test@example.com","is_primary":true}]}'
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

{
  "resource": {
    "uri": "https://api.calendly.com/contacts/CCCCCCCCCCCCCCCC",
    "emails": [
      {
        "email": "test@example.com",
        "is_primary": true
      }
    ],
    "created_at": "2026-01-15T18:01:09Z",
    "updated_at": "2026-01-15T18:01:09Z",
    "name": "Jane Doe",
    "phone_numbers": [
      {
        "phone_number": "+1 888-888-8888"
      }
    ],
    "timezone": "America/Los_Angeles",
    "job_title": "Director of Operations",
    "company": "ExampleCo",
    "country": "US",
    "state": "CA",
    "city": "San Francisco",
    "linkedin": "https://www.linkedin.com/in/janedoe",
    "custom_fields": [
      {
        "uri": "https://api.calendly.com/contacts/custom_field_definitions/CCCCCCCCCCCCCCCC",
        "value": "event",
        "label": "Lead source"
      }
    ],
    "first_email_date": "2026-01-08T11:00:00.000Z",
    "last_email_date": "2026-01-08T11:00:00.000Z",
    "next_meeting_date": "2026-01-08T11:00:00.000Z",
    "last_meeting_date": "2026-01-08T11:00:00.000Z",
    "last_interaction_date": "2026-01-08T11:00:00.000Z"
  }
}

Create a new Contact

Required scopes

contacts:write

Create a new Contact <Info title="Required scopes"> > `contacts:write` </Info>

Authentication

AuthorizationBearer

OAuth 2.0

AuthorizationBearer

Personal Access Token

Request

This endpoint expects an object.

namestringRequired

emailslist of objectsRequired

The user's email addresses. Max 10.

phone_numberslist of objectsOptional

The user's phone numbers. Max 10.

timezonestringOptional

job_titlestringOptional

companystringOptional

countrystringOptional

statestringOptional

citystringOptional

linkedinstringOptionalformat: "uri"

custom_fieldslist of objectsOptional

Custom field values to set on the contact. Each item requires a uuid (the custom field definition identifier) and a value; any other keys (such as label) are ignored. The entire request is rejected if any uuid is unknown, any value is the wrong type for its field (including an array for a scalar field or a scalar for an array field), or any single_select value is not one of the field definition’s option uuids.

Custom field values to set on the contact. Each item requires a `uuid` (the custom field definition identifier) and a `value`; any other keys (such as `label`) are ignored. The entire request is rejected if any `uuid` is unknown, any `value` is the wrong type for its field (including an array for a scalar field or a scalar for an array field), or any `single_select` `value` is not one of the field definition's option `uuid`s.

Response

Created

resourceobject

Information about a contact.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

500

Internal Server Error