An association links two records, such as a deal and the contact who is buying, or an invoice and the company it is billed to. Links are what let a team member open a contact in Alaaqat and see their deals, tickets and invoices in one place. When an integration creates records without linking them, each record stands alone and the team has to connect them by hand.
Every object can be linked to every other one, and a link always works both ways: link a product to a company, and the company also shows on the product.
| Requirement | Value |
|---|---|
| Token ability | {object}-update, where {object} is the record in the URL, such as company-update |
| Permission | The team member who created the key can edit that object, such as Edit Company Information |
See Permissions & Abilities for the abilities.
The record in the URL is the one you start from. Its path is one of /api/contacts, /api/companies, /api/deals,
/api/tickets, /api/products or /api/invoices. The record you link to it is named by the end of the URL and
by the body field:
| To link… | Link endpoint ends with | Link field | Unlink endpoint ends with | Unlink field |
|---|---|---|---|---|
| Contacts | /attach-contacts |
contact_ids |
/detach-contact |
contact_id |
| Companies | /attach-companies |
company_ids |
/detach-company |
company_id |
| Deals | /attach-deals |
deal_ids |
/detach-deal |
deal_id |
| Tickets | /attach-tickets |
ticket_ids |
/detach-ticket |
ticket_id |
| Products | /attach-products |
product_ids |
/detach-product |
product_id |
| Invoices | /attach-invoices |
invoice_ids |
/detach-invoice |
invoice_id |
A record can't be linked to a record of its own object, such as a company to another company.
Because a link works both ways, either side can create it. Linking a product to a company through
/api/companies/{id}/attach-products gives the same result as linking the company to the product through
/api/products/{id}/attach-companies. Only the ability the key needs changes: company-update for the first,
product-update for the second.
Companies, products and invoices can also be linked when you create them, with association_ids. See
Create a Company. Deals take contact_ids when you
create them.
POST https://app.alaaqat.com/api/{path}/{id}/attach-{objects}
Where {path} is the object of the record you start from, {id} is its _id, and {objects} is the object you
link to it, from the table above. Links one or more records to it. Records that are already linked stay linked.
{
"Accept": "application/json",
"Content-Type": "application/json"
}
{
[link_field: string]: string[]
}
| Field | Required | Validation | Description |
|---|---|---|---|
The link field, such as product_ids |
Required | An array of _ids of records of that object in your account |
The records to link. |
Linking two products to a company, with POST https://app.alaaqat.com/api/companies/6655a1b2c3d4e5f6a7b8c901/attach-products:
{
"product_ids": [
"6656b1c2d3e4f5a6b7c8d901",
"6656b1c2d3e4f5a6b7c8d902"
]
}
When one of the IDs isn't a record of that object in your account, nothing is linked and the request is refused
with 422. Invoices are the exception: when you link invoices, an ID that isn't one of your invoices is skipped
and the others are still linked.
200 OK, with every record of that object now linked under data, the ones linked before included. Each record
carries a few of its properties, enough to recognise it.
{
"data": [
{
"properties": {
"_id": "6656b1c2d3e4f5a6b7c8d901",
"name": "Ergonomic office chair",
"sku": "CH-ERGO-01",
"created_at": "2026-10-20T09:30:00.000000Z"
},
"account_id": 1024
},
{
"properties": {
"_id": "6656b1c2d3e4f5a6b7c8d902",
"name": "Standing desk",
"sku": "DK-STAND-02",
"created_at": "2026-10-18T11:00:00.000000Z"
},
"account_id": 1024
}
]
}
POST https://app.alaaqat.com/api/{path}/{id}/detach-{object}
Where {path} is the object of the record you start from, {id} is its _id, and {object} is the object of
the record to unlink, from the table above. Removes the link between the two records. Neither record is deleted.
{
"Accept": "application/json",
"Content-Type": "application/json"
}
| Field | Required | Validation | Description |
|---|---|---|---|
The unlink field, such as product_id |
Required | The _id of one record of that object that is linked to the record in the URL |
The record to unlink. |
Unlinking a product from a company, with POST https://app.alaaqat.com/api/companies/6655a1b2c3d4e5f6a7b8c901/detach-product:
{
"product_id": "6656b1c2d3e4f5a6b7c8d902"
}
Send the _id of a record that exists in your account. With any other value, the request fails and nothing is
unlinked.
200 OK, with the record from the URL under data.
{
"data": {
"properties": {
"_id": "6655a1b2c3d4e5f6a7b8c901",
"name": "Blue Harbor Trading",
"product_ids": [
"6656b1c2d3e4f5a6b7c8d901"
],
"products_count": 1,
"created_by": 12,
"updated_at": "2026-10-21T08:40:12.000000Z",
"created_at": "2026-10-20T09:30:00.000000Z"
},
"account_id": 1024
},
"message": "Entity was modified successfully."
}
The response of a single record, such as Show a Company, carries the
_ids of its linked records and their number, one pair for each object it is linked to:
| Field | Holds |
|---|---|
contact_ids, company_ids, deal_ids, ticket_ids, product_ids, invoice_ids |
The _ids of the linked records of that object |
contacts_count, companies_count, deals_count, tickets_count, products_count, invoices_count |
How many records of that object are linked |
A pair can be missing when the record has no link to that object.
To read the linked records themselves, with all their properties, call the list endpoint of the object you want, and name the record you start from with two query parameters:
| Key | Value |
|---|---|
| forAssociationType | The object of the record you start from, in the singular: contact, company, deal, ticket, product or invoice |
| forAssociationId | The _id of that record |
The products linked to a company:
GET https://app.alaaqat.com/api/products?forAssociationType=company&forAssociationId=6655a1b2c3d4e5f6a7b8c901
The answer is an ordinary paginated list, as List Products describes,
and the key needs the -index ability of the object you list, here product-index. The usual
Pagination and Complex Filtration
parameters still apply.
| Status | Meaning |
|---|---|
| 403 | The key lacks the {object}-update ability, the team member can't edit that object, or they can only change the records they or their teams own and the record in the URL isn't one of them. |
| 404 | No record with this _id in your account. |
| 422 | The link field is missing, or one of its IDs isn't a record of that object in your account. |