Calendeur
API key

API reference

Contacts

Every guest who books becomes a contact. Use these endpoints to look people up, keep their details in sync with your systems, and tag them.

List contacts

GET/api/v1/contacts

Contacts on the account, most recently updated first.

Scope: read:contacts

Query parameters

qstring

Search name, email or company.

emailstring

Exact email match.

tagstring

Only contacts with this tag.

limitinteger

Results per page, 1 to 100. Default 25.

cursorstring

The next_cursor from the previous page.

curl "https://calendeur.com/api/v1/contacts" \
  -H "Authorization: Bearer $CALENDEUR_API_KEY"
Response · 200
{
  "object": "list",
  "data": [
    {
      "id": "con_91a",
      "object": "contact",
      "name": "Alex Morgan",
      "email": "alex@example.com",
      "company": "Northwind",
      "job_title": "Operations Lead",
      "phone": null,
      "timezone": "America/Chicago",
      "tags": [
        "pilot"
      ],
      "source": "booking",
      "notes": null,
      "ai_insight": "Evaluating scheduling for a 40-person team. Next step: technical call.",
      "created_at": "2026-09-20T21:59:59.000Z",
      "updated_at": "2026-10-05T18:22:05.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create or update a contact

POST/api/v1/contacts

Matches on email: updates the contact if it exists (200), creates it otherwise (201).

Scope: write:contacts

Body

emailstringrequired

The contact's email.

namestring

Full name.

companystring

Company.

job_titlestring

Job title.

phonestring

Phone number.

timezonestring

IANA timezone.

tagsstring[]

Replaces the contact's tags.

notesstring

Free-form notes.

curl -X POST "https://calendeur.com/api/v1/contacts" \
  -H "Authorization: Bearer $CALENDEUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "alex@example.com",
  "name": "Alex Morgan",
  "company": "Northwind",
  "tags": [
    "pilot"
  ]
}'
Response · 201
{
  "id": "con_91a",
  "object": "contact",
  "name": "Alex Morgan",
  "email": "alex@example.com",
  "company": "Northwind",
  "job_title": "Operations Lead",
  "phone": null,
  "timezone": "America/Chicago",
  "tags": [
    "pilot"
  ],
  "source": "booking",
  "notes": null,
  "ai_insight": "Evaluating scheduling for a 40-person team. Next step: technical call.",
  "created_at": "2026-09-20T21:59:59.000Z",
  "updated_at": "2026-10-05T18:22:05.000Z"
}

Get a contact

GET/api/v1/contacts/{id}

One contact with their most recent bookings.

Scope: read:contacts

Path parameters

idstringrequired

The contact ID.

curl "https://calendeur.com/api/v1/contacts/ID" \
  -H "Authorization: Bearer $CALENDEUR_API_KEY"
Response · 200
{
  "id": "con_91a",
  "object": "contact",
  "name": "Alex Morgan",
  "email": "alex@example.com",
  "company": "Northwind",
  "job_title": "Operations Lead",
  "phone": null,
  "timezone": "America/Chicago",
  "tags": [
    "pilot"
  ],
  "source": "booking",
  "notes": null,
  "ai_insight": "Evaluating scheduling for a 40-person team. Next step: technical call.",
  "created_at": "2026-09-20T21:59:59.000Z",
  "updated_at": "2026-10-05T18:22:05.000Z",
  "recent_bookings": [
    {
      "id": "bkg_8f2k1q",
      "object": "booking",
      "event_type_id": "evt_30min",
      "host_user_id": "user_2hX",
      "contact_id": "con_91a",
      "status": "upcoming",
      "start": "2026-10-12T15:00:00.000Z",
      "end": "2026-10-12T15:30:00.000Z",
      "duration_minutes": 30,
      "guest": {
        "name": "Alex Morgan",
        "email": "alex@example.com",
        "phone": null,
        "company": "Northwind",
        "timezone": "America/Chicago"
      },
      "additional_guests": [],
      "notes": "Wants to discuss the onboarding flow",
      "location": "google_meet",
      "join_url": "https://meet.google.com/abc-defg-hij",
      "cancellation": null,
      "has_meeting_notes": false,
      "created_at": "2026-10-05T18:22:04.000Z",
      "updated_at": "2026-10-05T18:22:05.000Z"
    }
  ]
}

Update a contact

PATCH/api/v1/contacts/{id}

Changes only the fields you send. Takes the same fields as Create or update a contact.

Scope: write:contacts

Path parameters

idstringrequired

The contact ID.

curl -X PATCH "https://calendeur.com/api/v1/contacts/ID" \
  -H "Authorization: Bearer $CALENDEUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "job_title": "Head of Operations",
  "tags": [
    "pilot",
    "decision-maker"
  ]
}'
Response · 200
{
  "id": "con_91a",
  "object": "contact",
  "name": "Alex Morgan",
  "email": "alex@example.com",
  "company": "Northwind",
  "job_title": "Head of Operations",
  "phone": null,
  "timezone": "America/Chicago",
  "tags": [
    "pilot",
    "decision-maker"
  ],
  "source": "booking",
  "notes": null,
  "ai_insight": "Evaluating scheduling for a 40-person team. Next step: technical call.",
  "created_at": "2026-09-20T21:59:59.000Z",
  "updated_at": "2026-10-05T18:22:05.000Z"
}
PreviousMeeting notesNext Routing forms