Skip to content
XOS Developers

Create an agreement

People module

POST/agreementsagreements.create

A contractor MSA, offer letter or crew agreement with token signing. A signed agreement cannot be revoked or unsigned. Creates an agreement. Requires `Idempotency-Key`; a replay returns the original response. The organization is derived from the credential or the parent row, never from the body.

  • Requires the capability people.agreement.write.
  • OAuth scopes: people.
  • Send an Idempotency-Key header. A replay with the same key returns the original response.
  • Error statuses: 400, 401, 409, 422, 429. Errors are RFC 9457 problem details.

Request body: AgreementCreate

agreements.create: AgreementCreate
FieldTypeRequiredDescription
titlestringYesAgreement title.Constraints: length 1 to 300
agreement_kind"Offer Letter" | "Contractor Agreement" | "Master Services Agreement" | "Non-Disclosure Agreement"YesKind of agreement.
bodystringYesFull text the signer reads and signs; changes only while Proposed.Constraints: length 1 to 20000
project_idstring (uuid) | nullNoIdentifier of the project the agreement covers.
offer_idstring (uuid) | nullNoIdentifier of the offer the agreement follows.
person_idstring (uuid) | nullNoIdentifier of the person party to the agreement.
counterparty_idstring (uuid) | nullNoIdentifier of the external organization party to the agreement.
{
  "title": "Crew Agreement 2026",
  "agreement_kind": "Offer Letter",
  "body": "The crew member agrees to the call times in the schedule.",
  "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
}

Response 201: Agreement

agreements.create: Agreement
FieldTypeRequiredDescription
idstring (uuid)YesIdentifier of the agreement.
org_idstring (uuid)YesIdentifier of the owning organization, derived from the parent row and never accepted from the caller.
created_atstring (date-time)YesWhen the row was created.
created_bystring (uuid) | nullYesIdentifier of the person who created the row; null when a seed, platform or system process created it.
updated_atstring (date-time)YesWhen the row was last updated.
updated_bystring (uuid) | nullYesIdentifier of the person who last updated the row; null when a seed, platform or system process updated it.
titlestringYesAgreement title.Constraints: length 1 to 300
agreement_state"Proposed" | "Sent" | "Signed" | "Superseded" | "Expired" | "Canceled"YesAgreement state.
signed_atstring (date-time) | nullYesWhen the agreement was signed.
agreement_kind"Offer Letter" | "Contractor Agreement" | "Master Services Agreement" | "Non-Disclosure Agreement"YesKind of agreement.
bodystringYesFull text the signer reads and signs; changes only while Proposed.Constraints: length 1 to 20000
project_idstring (uuid) | nullYesIdentifier of the project the agreement covers.
offer_idstring (uuid) | nullYesIdentifier of the offer the agreement follows.
person_idstring (uuid) | nullYesIdentifier of the person party to the agreement.
counterparty_idstring (uuid) | nullYesIdentifier of the external organization party to the agreement.
token_expires_atstring (date-time) | nullYesWhen the signing link stops working.
signed_namestring | nullYesName the signer typed as their signature.Constraints: length 1 to 300
signed_body_sha256string | nullYesSHA-256 of the text that was signed, lowercase hex.Constraints: pattern ^[0-9a-f]{64}$
{
  "id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "org_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "created_at": "2026-10-08T14:30:00Z",
  "created_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "updated_at": "2026-10-08T14:30:00Z",
  "updated_by": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "title": "Crew Agreement 2026",
  "agreement_state": "Proposed",
  "signed_at": "2026-10-08T14:30:00Z",
  "agreement_kind": "Offer Letter",
  "body": "The crew member agrees to the call times in the schedule.",
  "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
  "token_expires_at": "2026-10-08T14:30:00Z",
  "signed_name": "Alex Rivera",
  "signed_body_sha256": "9f2c4e1a7b3d5f6e8a0c2e4f6a8b0d2c4e6f8a0b2c4d6e8f0a2b4c6d8e0f2a4b"
}

Code samples

curl -X POST "$XOS_BASE_URL/agreements" \
  -H "Authorization: Bearer $XOS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title":"Crew Agreement 2026","agreement_kind":"Offer Letter","body":"The crew member agrees to the call times in the schedule.","project_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","offer_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","person_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","counterparty_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}'
const { data } = await xos.agreements.create({
    "title": "Crew Agreement 2026",
    "agreement_kind": "Offer Letter",
    "body": "The crew member agrees to the call times in the schedule.",
    "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f",
    "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"
  });
response = xos.agreements.create({"title": "Crew Agreement 2026", "agreement_kind": "Offer Letter", "body": "The crew member agrees to the call times in the schedule.", "project_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "offer_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "person_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f", "counterparty_id": "0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"})
xos agreements create --data '{"title":"Crew Agreement 2026","agreement_kind":"Offer Letter","body":"The crew member agrees to the call times in the schedule.","project_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","offer_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","person_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f","counterparty_id":"0192f1e2-7c3a-7b4d-9e8f-1a2b3c4d5e6f"}'