Advanced Settings
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.
- Give the key a name that describes the tool that will use it, like "Website forms" or "Zapier".
- 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:writeandrecords:write. - Optionally set an expiry date.
- 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:
GET /v1/sectionslists your sections.GET /v1/sections/{uri}/schemalists every field with its id, type, and, for picklists, the valid options.- Use those field ids to read and write records:
POST /v1/sections/leads/recordswith afieldsobject keyed by field id.
Address fields come back as an object of parts, including line_1, line_2, town, county, postcode, lat and lng. When writing one you can send the same object, or just a single line of text such as "1 High Street, Anytown, AB12 3CD", and ORCA splits it up for you. If you send lat and lng, send both.
Building sections over the API
Normally a person builds a section in Settings and the API fills it. With the schema:write scope, a key can do the building too, which is handy when an agent or a script is setting up the very list it is about to load.
POST /v1/sectionscreates a section with its first template, its fields and, if you like, a Kanban board grouped by one of the new picklists, all in one call.PATCH /v1/sections/{uri}renames a section, changes its icon, or switches its Kanban board on or off. Theuriitself never changes, so nothing that already points at the section breaks.POST /v1/sections/{uri}/templatesadds a template, optionally with fields.POST /v1/sections/{uri}/fieldsadds fields to an existing section.PATCH /v1/fields/{id}renames a field, or changes whether it is required and how it shows in lists and on Kanban cards.POST /v1/fields/{id}/optionsadds options to a picklist.
Fields can be text, textarea, number, currency, date, time, checkbox, picklist, user, company, contact, file, address, section (a link to a record in another section) or formula. AI summary fields are still set up in Settings. Links and formulas are covered in the next part.
Adding fields is safe to repeat. A field that already exists with the same name and type is left alone, and any picklist options it is missing are added, so a script that retries after a timeout won't build everything twice. The whole request is checked before anything is written, so a mistake in the ninth field never leaves the first eight behind. A second POST /v1/sections with a uri that is already taken is refused rather than making a duplicate section. Every reply carries the section's full schema, the same as GET /v1/sections/{uri}/schema.
Links between sections, and formulas
A section field links each record to one record in another section, such as a timesheet to its job. To create one, send links_to with the uri of a section on the same account, so build that section first. A link can only hold one record, and what it points at can't be changed over the API afterwards.
When you write a record, the value for a link field can be any of these:
- the linked record's id
- what its key field reads, such as
"P-2210" - an object like
{"field": "Project No", "value": "P-2210"}, to match on another field of the linked section
The last two mean a script loading many rows needs no lookup for each one. If nothing matches, several records match, the record is in another section or account, or it has been deleted, the request is refused with a 422 saying which. You can also filter a record list by a link field, using either the id or the key.
A formula field needs a formula, for example {Hours} * {Rate}, where each name in braces is a field on the section (or one in the same request). ORCA checks the formula against the section's fields and tries it with sample values before anything is saved, so a typo is a 422 rather than a blank on every record. A formula can't be required. To change one later, use PATCH /v1/fields/{id} with a new formula. Formula values are worked out by ORCA, so they can't be written to over the API.
The schema read shows links_to on link fields and formula on formula fields.
The API builds and extends. It never takes apart:
- Nothing can be deleted: no sections, templates, fields or options.
- A field's type can't be changed, and nor can whether it holds more than one value. Both change what the stored values mean, so they stay in Settings, where a person can see the effect.
- A rename is refused if a formula or AI summary on the section refers to the field by name, since the rename would quietly break it.
- Options can't be added to a picklist that other fields share, because that would change those fields too, possibly on other sections.
Two things to know when issuing a schema:write key:
- Only someone who could build the same thing by hand can create a key with
schema:write. That means permission to create and update sections, templates and fields, and to create picklists and their options. If you don't have all of those, ORCA says so and doesn't create the key. - Existing keys don't pick it up. Create a new key with the scope ticked. A good habit is to create it for the job, then revoke it once the section is built.
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 and meetings. 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:
GET /v1/communications, with eithercontact_idorcompany_id. One of the two is required.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, and a text or email that names a job or project by its number can also be filed straight onto that record. The record route does the lookup for you: it returns everything filed on the record itself, plus everything filed against the contacts and company linked to it, newest first. A record with nothing linked or filed returns an empty list rather than an error.
Each communication carries a record_id, the record it was filed on, or null if it wasn't filed on one.
Both accept the same filters: method (Email, Telephone, Video Call, Post, In Person, LinkedIn), 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:
GET /v1/userslists the active users on your account, with?q=to search by name or email.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.
Bringing data across from another system
When you're moving from another CRM, the usual problem is that you'll load the same data more than once: a first pass, then again each week until you switch over. Three upsert endpoints handle that. Each row carries the old system's own ID, so ORCA can tell a row it has already seen from a new one.
POST /v1/companies/upsertneedscompanies:write.POST /v1/contacts/upsertneedscontacts:write.POST /v1/sections/{uri}/records/upsertneedsrecords:write.
No new scope: the write scopes already allow everything an upsert does.
A call names the source, the system the data comes from, and sends up to 200 rows, each with its source_id and its fields:
{
"source": "oldcrm",
"dry_run": true,
"rows": [
{ "source_id": "D-1042",
"fields": { "3037": "Proposal", "3801": 12000, "2201": { "source_id": "A-881" } } }
]
}
What happens to each row:
- A
source_idORCA has seen from that source is updated. Any other is created. Send the same rows twice and nothing is added twice. A row that would change nothing comes back asunchanged. - The source wins on every field a row supplies. An empty value (
null,""or[]) changes nothing, so an upsert never clears a field. UsePATCHfor that. Nothing is ever deleted. - Fields follow the ordinary write endpoints, with the same rules and messages: records by field id, companies and contacts by the same properties as
POST /v1/companiesandPOST /v1/contacts. - References by source ID. A company, contact or link field, and a contact's
company_id, can take{"source_id": "..."}, so a deal points at its account by the old system's ID with no lookup. The thing it points at must have been upserted already, so load companies, then contacts, then records. - Records typed in by hand are adopted. When a
source_idis new, a company already in ORCA under the same name, or a contact with the same email, is matched and takes the ID rather than being added again. Send"adopt": falseto switch that off. Records in a section match on the ID only. - A row that fails is skipped, with its
reason, and the rest still go in. Only a problem with the call itself, such as a missingsourceor more than 200 rows, refuses the whole call.
Send "dry_run": true first. Nothing is written, and the reply says what would happen: counts of create, update, unchanged and skip, and a line for each row. Run it again without dry_run when the numbers look right.
Use one source name for each system and keep to it. Upper and lower case don't matter. The names line up with the spreadsheet import, so a source you have loaded files from under the same name shares its IDs with the API.
A few things a key can't do here, because it has no person behind it:
- A stage that needs a sign-off is left out of the row, and the rest of the row goes in. The reply counts these in
held. - A barred record is skipped, and a section behind a barrier is "not found". Frozen records are skipped.
An upsert is a bulk load, so it fires no webhooks, just as a spreadsheet import fires none.
The full request and reply are in the API reference. For the other ways to bring data across, see Moving to ORCA.
Handing ORCA to an AI agent
An AI agent such as Claude can set ORCA up for you through the API: build your sections and fields, and bring your companies, contacts and records in. Settings > API Keys has a prompt ready to copy, written for your account. It tells the agent where the API is and how ORCA is shaped, and it sets out the ground rules:
- show you its plan in plain words and wait for your go-ahead before creating anything;
- send an
Idempotency-Keywith every POST; - look for a company or contact before adding it;
- import in small batches and check them;
- never delete without asking.
Make the key with the scopes the prompt lists (Tick the ones an agent needs does it for you), then paste the key into your agent yourself. The prompt never contains it. An agent can't create logins, log emails or calls, change settings or billing, or delete or retype fields. It can give a section an icon and a kanban board, and add fields of most kinds, including links between sections, addresses, tick lists and formulas. AI summary fields, line items, sign-offs, automations, approvals and the site clock are set up in Settings. While an account is read-only, writes are refused with a 402.
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.
- A record that has been frozen at a stage can't be changed or deleted over the API. The request is refused with a 409 and a message saying why. See Freeze and Revise.
- An API key isn't a person, so it can't be on a barrier's team. Barred sections and records come back as 404, and a link to a barred record reads "A record you can't open". If your account keeps an access log, each read is logged under the key's name.
- Requests are rate limited per key. If you get a 429, wait for the number of seconds in the
Retry-Afterheader. - Sending an
Idempotency-Keyheader 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.
