API Key
You must first create an API Key in Assembly. It is located under “Manage Integrations”, then scroll to the bottom and click “Manage API Keys”. Here, you can see your existing keys, their names and expiration. You can delete existing ones. When creating a new API key, the name must be unique in your organization. Once the key has been created, you will be shown a one-time dialog box with your new API key. You should copy this down somewhere safe — we will not show this again. If you lose your API key, you will need to make a new one.Accounts
Maintain your accounts through these API endpoints. Accounts types include: Company or Customer. In general you can refer to an account by appending its Assembly ID or domain to the URL. Or you can add the source specific ID of the account as a query parameter.Create Account
Required attributes aretype, name, and domain. The domain for a Company Account should be a domain i.e. company.com while the domain for a Customer Account should be an email i.e. name@company.com.
There are various optional attributes that you can add to define the account. The possible attributes are shown in the example below. You can also add source specific IDs that will then act as another id for you to reference the account with in lieu of using our Assembly ID for the account.
Note there are attributes specific to Company versus Customer Accounts:
- Company Specific Attributes:
company_typeandnumber_of_seats - Customer Specific Attributes:
role
{"id":"01945162-52fc-739b-98de-e2ac9f2eec49"}
Get Accounts
You can grab all the accounts for your organization by callingaccounts. This call is paginated, so please include the limit and offset in your URL otherwise the default limit=100 and offset=0 will be used.
The return type is {"accounts": {"data": [...], "has_next_page": ..., "next_cursor": ...}}.
The accounts are sorted by type so all Company Accounts will show up before Customer Accounts. Within each account type section, the accounts are sorted alphabetically by account name.
Each account will include multiple attributes in a key-value format. The attributes include id (the assembly id), name, domain, image_url, contract_value, contract_type, account_type, source_specific_ids, and others.
updated_after query parameter to return only accounts updated at or after a given time (updated_at >= updated_after) — useful for incremental sync. It accepts an RFC3339 timestamp (e.g. 2026-06-01T00:00:00Z) or a bare date (2026-06-01, treated as UTC midnight). Accounts with no updated_at are excluded when the filter is set, and an invalid value returns 400 - invalid updated_after parameter. The filter applies to the list path (with or without name) and covers both companies and contacts.
{"account":{...}}. Note that the source specific ID format is a bit different since it needs to be passed in as a query parameter.
Search Accounts
Search and filter accounts by additional properties, name, or domain with pagination support. This endpoint provides more advanced filtering capabilities compared to the standard GET accounts endpoint. Request Body Structure:- additional_properties (optional, array): Filter by attribute name and exact value match
- name (required if additional_properties provided): Attribute name
- value (required if additional_properties provided): Exact value to match
- name (optional): Filter by account name (case-insensitive partial match)
- domain (optional): Filter by account domain (case-insensitive partial match)
- limit (optional): Number of results per page (1-1000, default 50)
- offset (optional): Number of results to skip (default 0)
- updated_after (optional): Return only accounts updated at or after this time (
updated_at >= updated_after). Accepts an RFC3339 timestamp (2026-06-01T00:00:00Z) or a bare date (2026-06-01, treated as UTC midnight). Accounts with noupdated_atare excluded when set; an invalid value returns400 - invalid updated_after parameter.
- 400 Bad Request: Invalid request body, missing required fields, or pagination limits out of bounds
- 401 Unauthorized: Invalid or missing API key
- 500 Internal Server Error: Database or server errors
- If
additional_propertiesis provided, bothnameandvaluemust be present for each filter - Multiple
additional_propertiesfilters are combined with AND logic nameanddomainfilters use case-insensitive partial matching- Pagination follows the same pattern as GET /accounts endpoint
- Response format is identical to GET /accounts for consistency
Update Account
Update any of the account fields with this method. You can update an account via the Assembly ID, the domain of the account, or with a source specific ID that you’ve already linked to the account. In the input arguments, include any of the fields that you want to update. For updating additional properties, if the key already exists on the account then the value of that key will be updated, otherwise the whole key value pair will be added. If you want more granular actions for additional properties, please use the Additional Properties Endpoints. All the allowed parameters are the same as theCREATE endpoint except there are additional parameters for tags and source specific IDs.
The general tags will be tags that are being added and then there’s an additional removed_tags to indicate removing a tag. Similarily, the source_specific_ids will be added while the ‘removed_source_specific_ids’ will be removed.
The Assembly ID of the updated account is returned in the format {"id":"01945162-52fc-739b-98de-e2ac9f2eec49"}.
Upsert Account
A combination of the create and the update endpoints! If no Assembly ID, domain, nor source specific ID is passed in or if the values pass in don’t map to an existing account, then the account will be created. Otherwise, the existing account will be updated. The Assembly ID of the updated or created account is returned in the format{"id":"01945162-52fc-739b-98de-e2ac9f2eec49"}.
We recommend always inputting the required attributes for create (type, name, and domain) so that the endpoint won’t fail when the account needs to be created.
Delete Account
Delete an account by referencing the account with its Assembly ID, domain, or source specific ID. The return is empty{}.
Contacts
Endpoints for managing your contacts (customers who are apart of a company account). These endpoints are similar in format to the Accounts APIs. In general you can refer to a contact by appending its Assembly ID or domain to the URL. Or you can add the source specific ID of the contact as a query parameter.Create Contact
Required attributes arename,domain (email i.e. name@company.com), and some sort of company identifier. For the company identifier, you need to include the Assembly ID of the company in company_id, the domain of the company in company_domain, or the source specific ID of the company in company_source_specific_id.
There are various optional attributes that you can add to define the contact, all the options are shown below. You can also add source specific IDs that will then act as another id for you to reference the contact with in lieu of using our Assembly ID for the contact.
The Assembly ID of the created contact is returned in the format {"id":"01966e6b-3219-78be-a0fe-260e590565f5"}
Get Contacts
You can grab all the contacts for your organization by callingcontacts. This call is paginated, so please include the limit and offset in your URL otherwise the default limit=100 and offset=0 will be used.
The return type is {"contacts": {"data": [...], "has_next_page": ..., "next_cursor": ...}}.
{"contacts":{...}}. Note that the format for passing in the source specific ID is a bit different, it needs to be passed in as a query parameter.
updated_after query parameter to return only contacts updated at or after a given time (updated_at >= updated_after) — useful for incremental sync. It accepts an RFC3339 timestamp (e.g. 2026-06-01T00:00:00Z) or a bare date (2026-06-01, treated as UTC midnight). Contacts with no updated_at are excluded when the filter is set, and an invalid value returns 400 - invalid updated_after parameter. This works on both the all-contacts list and the by-company list shown above.
{"contact":{...}}
Update Contact
Update any of the contact’s fields via the Assembly ID, the domain of the contact, or with a source specific ID that you’ve already linked to the contact. In the input arguments, include any of the fields that you want to update. For updating additional properties, if the key already exists on the account then the value of that key will be updated, otherwise the whole key value pair will be added. If you want more granular actions for additional properties, please use the Additional Properties Endpoints. All the allowed parameters are the same as theCREATE endpoint except there are additional parameters for tags and source specific IDs.
The general tags will be tags that are being added and then there’s an additional removed_tags to indicate removing a tag. Similarily, the source_specific_ids will be added while the ‘removed_source_specific_ids’ will be removed.
The Assembly ID of the updated contact is returned in the format {"id":"01966e6b-3219-78be-a0fe-260e590565f"}.
Upsert Contact
A combination of the create and the update endpoints! If no Assembly ID, domain, nor source specific ID is passed in or if the values pass in don’t map to an existing contact, then the contact will be created. Otherwise, the existing account will be updated. The Assembly ID of the updated or created contact is returned in the format{"id":"01966e6b-3219-78be-a0fe-260e590565f"}.
We recommend always inputting the required attributes for create (name, domain, and one of the company identifiers so company_id, company_domain or company_source_specific_id) so that the endpoint won’t fail when the contact needs to be created.
Delete Contact
Delete a contact by referencing the contact with its Assembly ID, domain, or source specific ID. The return is empty{}.
Deals
Manage deals (opportunities) linked to your company accounts through these API endpoints. You can reference a deal by its Assembly ID or by a source specific ID you have already linked to it. A source specific ID (source_specific_ids) is your own external identifier for a deal — for example a HubSpot deal ID or a Salesforce opportunity ID. An account source specific ID (account_source_specific_id) is the external identifier you used when creating the parent company account.
Create Deal
Required attributes arename and account_source_specific_id. The account_source_specific_id must match a source specific ID that was already registered on an existing company account.
You can optionally supply source_specific_ids — an array of your own external IDs for this deal — so that you can look it up later without the Assembly UUID. The Assembly ID of the created deal is returned in the format {"id":"01945162-52fc-739b-98de-e2ac9f2eec49"}.
Get Deal
Fetch a single deal by its Assembly UUID or by a source specific ID you have linked to it. The deal is returned in the format{"deal": {...}}.
Get Deals
List all deals for your organisation or narrow the list to a single company account. This call is paginated — includelimit and offset in the URL, otherwise the defaults limit=100 and offset=0 are used. The deals are returned in the format {"deals": [...]}, sorted by creation date (newest first).
updated_after query parameter to return only deals updated at or after a given time (updated_at >= updated_after) — useful for incremental sync. It accepts an RFC3339 timestamp (e.g. 2026-06-01T00:00:00Z) or a bare date (2026-06-01, treated as UTC midnight). Deals with no updated_at are excluded when the filter is set, and an invalid value returns 400 - invalid updated_after parameter. The filter applies to both list paths (all-org and account_source_specific_id); it is ignored on the single-deal source_specific_id lookup. Each deal in the response already includes an updated_at field.
Update Deal
Update any fields on an existing deal. Reference the deal by its Assembly UUID (path parameter) or by a source specific ID (query parameter). Only the fields you include in the body are changed. Forsource_specific_ids, the values you provide will be added to the deal. Use removed_source_specific_ids to remove existing ones. The Assembly ID of the updated deal is returned in the format {"id":"01945162-52fc-739b-98de-e2ac9f2eec49"}.
Upsert Deal
A combination of create and update. If the deal already exists (matched by Assembly UUID in the path or by a source specific ID in the body) it will be updated in place. Otherwise a new deal is created. We recommend always including the fields required for creation (name and account_source_specific_id) so the endpoint never fails when the deal needs to be created for the first time. The Assembly ID of the created or updated deal is returned in the format {"id":"01945162-52fc-739b-98de-e2ac9f2eec49"}.
Delete Deal
Delete a deal by its Assembly UUID (path parameter) or by a source specific ID (query parameter). This also removes the linked source specific ID rows and any custom attribute values for that deal. The Assembly ID of the deleted deal is returned in the format{"id":"01945162-52fc-739b-98de-e2ac9f2eec49"}.
Additional Properties
The custom attributes are stored on a per item basis. Therefore, all of these endpoints affect a specific account’s, contact’s, or deal’s additional properties. In general, the additional properties endpoints are in this formatadd_props/:item/:id, where :item is one of accounts, contacts, or deals.
Create Additional Properties
To denote which account, contact, or deal to create the property on, you have to append the item (accounts, contacts, or deals) and either the item’s Assembly ID, source specific id, or domain (accounts and contacts only) to the url.
Then include a map of the properties you want to add to the value of each property. If the property already exists on that item’s additional properties, an “already exists” error will be returned. Otherwise, the Assembly ID of the item that the property was created for is returned in the format {"id":"01945162-52fc-739b-98de-e2ac9f2eec49"}.
Get Additional Properties
Specify the item (accounts, contacts, or deals) and either the Assembly ID, domain (accounts and contacts only), or source specific ID of the item to get the additional properties.
The return includes the ID of the item and its additional properties in this format {"id": "01945162-52fc-739b-98de-e2ac9f2eec49", "additional_properties": [...]}
updated_after query parameter to return only attribute values updated at or after a given time (updated_at >= updated_after) — useful for incremental sync. It accepts an RFC3339 timestamp (e.g. 2026-06-01T00:00:00Z) or a bare date (2026-06-01, treated as UTC midnight). Values with no updated_at are excluded when the filter is set, and an invalid value returns 400 - invalid updated_after parameter.
Update Additional Properties
Update an item’s additional properties by specifying the item (accounts, contacts, or deals) and either the item’s Assembly ID, domain (accounts and contacts only), or source specific ID. Include any of the fields that we want to update with a mapping to their new values.
If the specified field does not already exist in the item’s additional properties, we will directly add it. The ID of the item whose additional properties were updated is returned in the format {"id": "01945162-52fc-739b-98de-e2ac9f2eec49"}
Delete Additional Property
Similarly, specify the item (accounts, contacts, or deals) and its Assembly ID, domain (accounts and contacts only), or source specific ID and then specify which properties to delete by the property names. The return is empty {}.
Labels
Here are the API endpoints for account labels. Account label types include:Tier, Stage, CompanyType, or AccountTag (Tags).
Create Label
Required attributes are thetype, name, and color of the label. Optionally, include a description. The ID of the created label will be returned in this format {"id": "0195a666-3405-7664-aaf1-ad65b6091e96"}.
Get Labels
There are three versions of grabbing account labels. You can grab all the account labels for your organization by calling/account/labels.
To grab a specific type of account labels, add the label type so /account/labels/{type}. And then to grab a specific label, add the label ID so /account/labels/{label_id}.
The labels are returned in this format {"labels": [...]}.
updated_after query parameter to return only labels updated at or after a given time (updated_at >= updated_after) — useful for incremental sync. It accepts an RFC3339 timestamp (e.g. 2026-06-01T00:00:00Z) or a bare date (2026-06-01, treated as UTC midnight). Labels with no updated_at are excluded when the filter is set, and an invalid value returns 400 - invalid updated_after parameter.
Update Label
To update an account label, you must have the label id and call/account/labels/{label_id}. Use the get account labels endpoints to grab the label id if needed.
Include the fields that you are changing for the label in the json object. The possible arguments are type, name, color, and description. The ID of the updated label is returned as {"id": "0195a666-3405-7664-aaf1-ad65b6091e96"}
Delete Label
You also must have the label_id to delete an account label. Then just call/account/labels/{label_id} with a delete operation. The return is empty {}.
Usage
Here are the API endpoints for sending usage logs to be stored under a specific account.Add Usage Log
The required attributes are:timestamp: when the event happenedtype: the type of log, the options are “Action”, “Metric”, or “CumulativeMetric”content: what happened in the log (think the string that shows up in your logs)attribute: the category that the log is related to, we’ll use this attribute to group logs together for account 360s and for calculating health scores (i.e. “Login” or “AccountSpend”)value: if the type of the log is “Metric” or “CumulativeMetric”, we require you to pass in the value of the metric so that we can use it for grouping and filtering (i.e. $20 or 7) Additionally, you can add any metadata that you want to store. The ID of the created log is returned in this format{"id": "01945162-52fc-739b-98de-e2ac9f2eec49"}.
accounts or contacts) and its Assembly ID, source specific id, or domain in the url.
Get Usage Logs
You can either grab all the usage logs for your organization or specify a specific account/contact through one of the three identifying methods. This call is also paginated, so please include the limit and offset in your URL otherwise the defaultlimit=100 and offset=0 will be used.
Note: the logs are returned in decreasing timestamp order so the newest logs are returned first.
The logs are returned in this format {"logs": {"data": [...], "has_next_page": ..., "next_cursor":...}}
updated_after query parameter to return only usage logs updated at or after a given time (updated_at >= updated_after) — useful for incremental sync. It accepts an RFC3339 timestamp (e.g. 2026-06-01T00:00:00Z) or a bare date (2026-06-01, treated as UTC midnight). Logs with no updated_at are excluded when the filter is set, and an invalid value returns 400 - invalid updated_after parameter. The filter works on the org-wide list and the per-account/contact lists.
Update Usage Log
Update any values in a usage log by the usage log’s ID. Include the values that you want to update in the input data. Note, that updating the metadata field will completely override the existing metadata value. The ID of the updated log is returned in this format{"id": "01945162-52fc-739b-98de-e2ac9f2eec49"}.
Delete Usage Log
Delete a usage log by its specific ID which is returned when a usage log is created. The return is empty{}.
Other
Create Account Note
Create (or idempotently upsert) an Account Note for a company resolved by domain. Use this endpoint for CRM/meeting note ingestion (e.g., meeting notes from Gong, Salesforce, etc.). The endpoint:- Resolves the primary company for the provided domain (
is_primary=true) within the org - Stores note content and meeting metadata (including raw participant emails)
- Performs idempotent upsert using
(org_id, source, source_specific_id)— repeated calls with the samesourceandsource_specific_idupdate the same record instead of creating duplicates
/accounts/create_note
Authentication: API key via header Authorization: <API_KEY> (required)
Request body (JSON):
| Field | Type | Required | Description |
|---|---|---|---|
domain | string | Yes | Domain used to resolve the company (e.g. "berkeley.edu"). Must map to an existing primary company for the org. |
source | string | Yes | Source system identifier (e.g. "gong", "salesforce"). Treated as an opaque string. |
source_specific_id | string | Yes | Unique ID for this note in the source system (used for idempotency). |
note | string | Yes | The note content/body. |
original_timestamp | string | Yes | Meeting time in RFC3339 format (e.g. "2025-02-25T14:30:00Z"). |
participants | array of strings | Yes | Raw participant emails (stored in meeting metadata). |
title | string | No | Optional title for the note. |
action_items | string | No | Optional action items extracted from the note. |
transcript | string | No | Optional full transcript. |
{"id": "uuid"}. The stored note includes org_id, company_id, source, source_specific_id, and metadata.meeting.participant_emails (array of strings, when provided).
Idempotency: Calls with the same (source, source_specific_id) within an org will update the existing note instead of creating a duplicate.
Error cases: 401 Unauthorized (missing/invalid Authorization), 400 Bad Request (invalid payload), 412 Precondition Failed (domain does not correspond to an existing company account), 502 Bad Gateway (upstream error).