Associations between records

Discover the other side#

An association is named after the target resource. Read /resources/{resource} and inspect associations before building a relationship. The key’s resource allowlist must include both the source and the target, and its owner must be allowed to access both records.

Read, link and unlink#

GET /{resource}/{id}/{association} lists links. PUT /{resource}/{id}/{association}/{target_id} creates or updates a link, with an optional object of link fields. Creation returns 201; an existing link returns 200. DELETE on the same target path removes the link, takes no body, and returns 404 if it did not exist. PUT and DELETE support Idempotency-Key.

read -r -p 'Company id: ' COMPANY_ID
read -r -p 'Contact id: ' CONTACT_ID
read -r -p 'Unique link operation key: ' LINK_KEY
curl --fail-with-body --request PUT "$SQUARIO_API_BASE/companies/$COMPANY_ID/contacts/$CONTACT_ID" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $LINK_KEY" \
  --data '{"job_title":"Operations lead","is_primary":true}'

curl --fail-with-body "$SQUARIO_API_BASE/companies/$COMPANY_ID/contacts" \
  --header "Authorization: Bearer $SQUARIO_API_KEY"

read -r -p 'Unique unlink operation key: ' UNLINK_KEY
curl --fail-with-body --request DELETE "$SQUARIO_API_BASE/companies/$COMPANY_ID/contacts/$CONTACT_ID" \
  --header "Authorization: Bearer $SQUARIO_API_KEY" \
  --header "Idempotency-Key: $UNLINK_KEY"

Employment has its own rules#

Company/contact links accept job_title, department, role_label, role_description, decision_power, buying_role, is_primary, is_decision_maker, is_billing_contact, is_technical_contact, started_at and notes. Consult the reference for their types and options.

• A new link defaults to is_primary: false. Making it primary demotes the contact’s previous primary company.
• Omitting is_primary on an existing link preserves its value.
• DELETE ends the employment with today’s date and clears its primary flag. Ended links disappear from the association list.
• Deleting a project’s primary deal link returns 409; change that primary relationship in the app first.

Understand a link response#

Each link exposes the two record identifiers, its allowed link fields and timestamps, without the link table’s own identifier, author or internal metadata. List responses include data and meta: { page, page_size, has_more }, ordered oldest first, with no total count. Link pages default to 100 and accept 1–100. Withheld link fields are null, including boolean flags; a boolean PUT field still requires a boolean.