External references
Jobs and customers accept an optional external_reference when you create them: your own system's identifier for the record. You can look the record up by it later without storing FieldTask IDs.
Rules
- 1–128 characters, not only whitespace, and no control characters.
- Stored exactly as sent: case-sensitive, never trimmed or normalized.
- Unique per organization and client application. A second record of the same kind with the same reference is rejected with
409 external_reference_conflict, and the existing record isn't changed. - Only jobs and customers accept it. Other creates reject the field.
- It isn't returned in record bodies.
Look a record up
curl --get "$FIELDTASK_API_ORIGIN/public/v1/jobs" \
--header "Authorization: Bearer $FIELDTASK_API_TOKEN" \
--data-urlencode "external_reference=example-crm-job-10482"
The response is a normal list with zero or one record. The external_reference parameter can't be combined with any other parameter, and only finds records created through your client application.
References and idempotency keys
They solve different problems, so use both:
| External reference | Idempotency key | |
|---|---|---|
| Identifies | A record, permanently | One create request, for 7 days |
| Visible to | Your client application's lookups | Retries of the same request |
| Reuse it | To find the same record | To retry the same create |
When a create's outcome is unknown and the idempotency window has passed, look the record up by its external reference before creating it again.