Skip to content
Caraer Developers

Connect records with relations

Link an existing candidate to an existing vacancy without copying either record. You need their UUIDs, a relation defined between the objects, and permission to write that relation. Resolve the relation’s internal name from the schema first.

Section titled “Add and remove a link”

Use these endpoints to link two existing records with a named relation. The route is:

  • POST /api/v2/records/relations/{fromUuid}/{relationName}/{toUuid}
  • DELETE /api/v2/records/relations/{fromUuid}/{relationName}/{toUuid}

Create a relation between two records

Section titled “Create a relation between two records”

Example: link candidate FROM_UUID to vacancy TO_UUID using relation applied_for.

Terminal window
curl -X POST "https://v2.api.caraer.com/api/v2/records/relations/FROM_UUID/applied_for/TO_UUID?primary=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

What happens on create:

  • Backend loads both records and the relation by relationName.
  • If one of them does not exist, the request fails with a not-found error.
  • The relation direction is resolved against relation schema (from/to) in backend logic, so use the relation name exactly as defined.
  • The relation is merged (created if missing, updated if already present).

Delete a relation between two records

Section titled “Delete a relation between two records”

This removes the relation edge between those record UUIDs for that relation name.

Terminal window
curl -X DELETE "https://v2.api.caraer.com/api/v2/records/relations/FROM_UUID/applied_for/TO_UUID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

What happens on delete:

  • It checks relation delete access on both involved objects.
  • It deletes matching relation edge(s) for that relation between the two UUIDs.

How primary works for relations

Section titled “How primary works for relations”

primary is a query parameter on relation creation:

  • primary=false (default): creates/updates the relation without primary selection behavior.
  • primary=true: marks this specific relation edge as the primary one.

Important primary behavior:

  • The created relation gets primary = true.
  • For the same relation type and same target record (toUuid), other incoming relation edges are set to primary = false.
  • Practical result: you can enforce a single “main” linked record for a target record within that relation type.

Example:

Terminal window
curl -X POST "https://v2.api.caraer.com/api/v2/records/relations/CANDIDATE_UUID/applied_for/VACANCY_UUID?primary=true" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

primary vs primary_object (do not confuse these)

Section titled “primary vs primary_object (do not confuse these)”
  • Relation primary is metadata on a relation edge between two records.
  • primary_object is metadata on the record node itself and represents that record’s main object context.

They solve different problems and are managed separately.