Using the ORCA API

The ORCA API lets your own systems read and write the data in your account: contacts, companies, custom section records, to-dos, and calendar events, plus a read-only staff directory and read-only access to logged emails and calls. If you want your website, back office, or an automation tool like Zapier talking to ORCA, this is the way in.

The full endpoint-by-endpoint reference lives at api.orca-crm.com/docs. This page covers the ideas you need before you read it.

Creating an API key

Head to Settings → API Keys. You will need the settings permission on your account.

1. Give the key a name that describes the tool that will use it, like "Website forms" or "Zapier".
2. Tick the scopes it needs. Scopes are per resource, split into read and write, so a key that only submits new leads needs nothing more than contacts:write and records:write.
3. Optionally set an expiry date.
4. Click Create key and copy the key straight away. For security it is shown exactly once. If you lose it, revoke it and create another.

A key belongs to your account, not to a person. Anything created with it is attributed to the key's name, so a well-named key gives you a clean audit trail.

Making a request

Send the key as a bearer token:

curl https://api.orca-crm.com/v1/ping \
  -H "Authorization: Bearer orca_your_key_here"

A successful reply confirms the account and the key's scopes. From there, the shape is conventional REST: GET /v1/contacts lists, POST /v1/contacts creates, PATCH updates, DELETE removes. Everything is JSON.

Working with custom sections

Your custom sections (Leads, Jobs, Deals, whatever you have built) are fully available. Because every account's fields are different, the API describes them to you:

1. GET /v1/sections lists your sections.
2. GET /v1/sections/{uri}/schema lists every field with its id, type, and, for picklists, the valid options.
3. Use those field ids to read and write records: POST /v1/sections/leads/records with a fields object keyed by field id.

Reading logged emails and calls

Everything logged against a contact or company can be read back: the emails captured by copying comms@orca-crm.com, along with calls, meetings, and call reports. Useful when you want your own tools to know what was last said to a customer, not just what is sitting in the fields.

This needs the communications:read scope, which is separate from records:read on purpose. Every other read scope hands back field values. This one hands back the text of customer emails, so it is something you switch on deliberately rather than something a key picks up along the way.

Two ways in:

1. GET /v1/communications, with either contact_id or company_id. One of the two is required.
2. GET /v1/records/{uuid}/communications, for the conversation attached to a record.

The second is usually the one you want, and it is worth knowing why it exists. Communications are filed against the contact and the company rather than against a record, which is how the copy-in capture works out where to put an incoming email in the first place. The record route does that lookup for you: it finds the contacts and company linked to the record and returns everything filed against them, newest first. A record with nothing linked to it returns an empty list rather than an error.

Both accept the same filters: method (Email, Telephone, Video Call, Post, In Person), is_call_report to separate written-up calls from captured correspondence, date_from and date_to, and updated_since for polling.

It is read-only. Nothing here sends, edits, or deletes. Attachments are reported as a has_attachment flag rather than a link, so fetch the files themselves from ORCA.

Looking up user ids

Some writes take a user id: assigning a to-do with assigned_user_id, or attributing a write to a staff member with acting_user_id. Rather than digging those ids out of the ORCA interface, give your key the users:read scope and ask the API:

1. GET /v1/users lists the active users on your account, with ?q= to search by name or email.
2. GET /v1/users/{id} fetches one.

It is read-only and deliberately minimal: id, name, email, and timestamps. No phone numbers, no preferences, and no way to create or change users through the API. User management stays in ORCA itself.

Good to know

• Every key sees exactly one account. There is no way to reach another account's data with your key, whatever you put in the request.
• Requests are rate limited per key. If you get a 429, wait for the number of seconds in the Retry-After header.
• Sending an Idempotency-Key header with a POST means a retry cannot create a duplicate. Recommended for anything that fires automatically.
• Revoking a key takes effect immediately. Anything still using it starts receiving 401s.
• The API also works in reverse: webhooks let ORCA call your systems the moment something changes, instead of you polling for it.

The webhook token on Settings → General is a separate, simpler thing: it lets ORCA support wire up public website forms for you. The API keys described here are for your own integrations.

If you get stuck, email support@orca-crm.com and we will point you the right way.