Associations

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.

Which records can be linked

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.

Link records

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.

Header

{
    "Accept": "application/json",
    "Content-Type": "application/json"
}

Body

{
    [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.

Response

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
        }
    ]
}

Unlink a record

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.

Header

{
    "Accept": "application/json",
    "Content-Type": "application/json"
}

Body

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.

Response

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."
}

Read the links of a record

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.

List the records linked to a record

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.

Errors

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.