Developer interface
A JSON interface for reading and creating claims from your own systems. Use it to raise claims automatically from a returns process, to mirror claim status into a data warehouse, or to post updates from wherever your team already works.
Included on Business and Enterprise. A key keeps working if you move down a plan, but requests are refused until you move back up, so nothing breaks silently on your side without an explanation in the response.
Getting a key
Go to Settings, then API and issue a key. You will be asked to confirm your password first, because a key outlives the session that created it.
The key is shown once and never again. We store only a hash of it, so we genuinely cannot recover it for you. If you lose it, revoke it and issue another. A key looks like this:
cc_1a2b3c4d.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
The part before the full stop identifies the key and appears in your settings screen and in our logs. The part after it is the secret. Treat the whole string as a password: it carries full access to your organisation's claims, and it is scoped to that organisation only.
Authenticating
Send the key as a bearer token on every request.
curl https://claimcore.co.uk/api/claims/ \ -H "Authorization: Bearer cc_1a2b3c4d.your-secret-here"
Session cookies are deliberately not accepted. Being signed in to Claim Core in your browser does not authenticate a request here.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /api/claims/ | List claims, newest first |
POST | /api/claims/ | Create a claim |
GET | /api/claims/<reference>/ | Fetch one claim in full |
GET | /api/claims/<reference>/comments/ | List comments the brand can see |
POST | /api/claims/<reference>/comments/ | Add a comment |
There is no endpoint for changing a claim's status. Decisions are deliberately made by a person in the product, where the reasoning and the audit trail are captured together.
Creating a claim
POST /api/claims/
{
"brand_id": "8f14e45f-ceea-467a-9f0e-6a1b0c2d3e4f",
"order_reference": "1042",
"notes": "Raised automatically from the returns portal",
"lines": [
{
"claim_type": "damaged_item",
"description": "Linen throw arrived torn",
"sku": "LT-OAT-01",
"quantity": 1,
"unit_value": "89.00"
}
]
}
brand_id and
order_reference
are required. Lines are optional, and each one needs a valid claim type and a description. Quantity
must be a whole number of at least one, and values are validated before anything is written, so a
bad line never leaves a half-created claim behind.
A successful create returns 201 with the full claim, including the reference your team will see.
When something goes wrong
Errors always come back as JSON in the same shape.
{ "error": { "code": "validation_error", "message": "lines[0].quantity must be a whole number between 1 and 1000000." } }
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_json | The body was not a JSON object |
| 401 | unauthorized | Key missing, malformed, revoked or expired |
| 403 | plan_required | Your plan no longer includes this interface |
| 404 | not_found | No such claim in your organisation |
| 422 | validation_error | A field was missing or out of range |
| 422 | invalid_brand | Unknown brand, or not yours |
| 422 | quota_exceeded | Monthly claim allowance reached |
| 429 | rate_limited | Too many requests this minute |
Rate limits
120 requests per minute per key, counted in fixed one-minute windows. Failed authentication is throttled separately, by source address, so a leaked prefix cannot be used to hammer the service.
If you need a higher limit for a bulk backfill, talk to us before you run it rather than discovering the ceiling in production.
Looking after your keys
- Issue a separate key per integration, so you can revoke one without taking the others down.
- Give a key an expiry date when it is for a one-off migration.
- Revoking takes effect on the very next request. There is no cache to wait for.
- Issuing and revoking are both recorded in your audit log, with who did it.