Create and update records

Store a candidate in Caraer, update their details, and avoid creating duplicates when an integration retries.

Before you begin

• Read API authentication.
• Use a sandbox company with a candidate object and the properties below.
• Confirm the token has the required object and property write permissions.

Create a record

curl -X POST 'https://v2.api.caraer.com/api/v2/records/candidate?parse=true' \
  -H "Authorization: Bearer $CARAER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"properties":{"firstname":"Alex","email":"alex@example.com"}}'

The response contains the saved record. Keep its UUID for later requests. Check the returned values; a successful request is not evidence that a downstream webhook or provider completed its work.

Update a record

curl -X PUT "https://v2.api.caraer.com/api/v2/records/candidate/$RECORD_UUID?parse=true" \
  -H "Authorization: Bearer $CARAER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"properties":{"firstname":"Alexander"}}'

Use the existing UUID. Inspect the returned record before marking the update complete in your integration.

Avoid duplicates on retries

For repeatable imports, use POST /api/v2/records/{objectName}/createOrUpdate with the object’s configured unique fields. A field appearing unique in your source does not make it unique in Caraer: check the schema first.

curl -X POST 'https://v2.api.caraer.com/api/v2/records/candidate/createOrUpdate' \
  -H "Authorization: Bearer $CARAER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"properties":{"email":"alex@example.com","firstname":"Alex"}}'

Send the correct field values

Use internal property names and option values. Treat file, structure, range, and select fields according to their declared format. The property value guide contains the value shapes and submission checklist.

File visibility before success

A successful record create or update applies the file property’s configured visibility to company files adopted by that write. This covers existing file keys, imported URLs, and inline uploads in both file and multi-file formats, including writes with lifecycle events disabled. Attachment linking still runs in the background. External references and files belonging to another company do not have their storage permissions changed.

For example, after confirming that resume_file is a writable file property and that the key belongs to the selected company, update the candidate:

curl -X PUT "https://v2.api.caraer.com/api/v2/records/candidate/$RECORD_UUID?parse=true" \
  -H "Authorization: Bearer $CARAER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"properties":{"resume_file":"COMPANY_UUID/files/candidates/jane-doe-cv.pdf"}}'

On success, the saved file has the property’s configured visibility before the response returns. This does not grant permission to write read-only properties.

If storage cannot apply visibility, the write returns HTTP 500 even though the record and its already committed files remain saved. Read the record before retrying; do not assume the error rolled back the write or blindly create a second record. Check file access separately before treating the upload as ready. See property values for value shapes and the Records API reference for request and response contracts.

Continue the workflow

• Find records and paginate.
• Link records.
• Archive and restore records.
• Extend a record into another object.

Common mistakes

Using a display label as a property name, writing a computed/linked value, or blindly retrying create requests can produce validation errors or duplicates. Inspect the schema and returned record rather than guessing a payload.

See the Records API reference for the full request and response contracts.