curl --request POST \
--url https://api.osaconnection.com/v1/claims \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"external_id": "CMS-884512",
"claim_number": "FL-2026-0091832",
"adjuster_osa_id": "Xk3pQ9vT2mN8rL5wB7yC1dF4gH6j",
"loss": {
"date": "2026-09-27"
},
"policy": {
"number": "8705123456"
},
"carrier": {
"name": "Gulf Coast Mutual Insurance"
},
"loss_location": {
"street": "418 Bayshore Drive",
"city": "Tampa",
"state": "FL",
"zip": "33606"
},
"policyholder": {
"first_name": "Maria",
"last_name": "Delgado",
"phone": "8135550142"
}
}
'{
"id": "3f8a2c61-5b7e-4d2a-9c1e-7a4b2d9e6f10",
"external_id": "CMS-884512",
"claim_number": "FL-2026-0091832",
"test": false,
"created_at": "2026-09-28T14:32:11Z",
"updated_at": "2026-09-28T14:32:11Z",
"assignment": {
"status": "pending_acceptance",
"adjuster_osa_id": "Xk3pQ9vT2mN8rL5wB7yC1dF4gH6j",
"responded_at": null,
"rejection_reason": null
},
"loss": {
"date": "2026-09-27",
"peril": "flood"
},
"policy": {
"number": "8705123456"
},
"carrier": {
"name": "Gulf Coast Mutual Insurance"
},
"loss_location": {
"street": "418 Bayshore Drive",
"city": "Tampa",
"state": "FL",
"zip": "33606"
},
"policyholder": {
"first_name": "Maria",
"last_name": "Delgado",
"phone": "8135550142"
}
}Send a claim to an adjuster
Creates a claim in your firm and offers it to the adjuster named by adjuster_osa_id.
The adjuster accepts or rejects it in the OSA app; until then the claim’s
assignment.status is pending_acceptance. Poll GET /v1/claims to see the outcome.
Who can receive a claim. The adjuster must be an active member of your firm who has
accepted your invitation, holds the permission to accept claims, and is accepting
assignments. Otherwise the request fails with 422 unknown_osaid,
adjuster_not_in_firm or adjuster_not_accepting.
Test keys. A claim sent with an osa_test_ key must go to one of your firm’s test
accounts and is permanently a test claim (test: true). Real adjusters are invisible to
test keys, so naming one fails with 422 adjuster_not_in_firm. A live key naming a test
account fails with 422 environment_mismatch.
Duplicates. Duplicates are checked within your firm and within the key’s environment
(test or live), so test claims and live claims never collide. Reusing an external_id
returns 409 duplicate_claim; so does a claim_number that matches one of your firm’s
open claims sent through the API in the same environment. The error includes the
existing claim’s id, which your key can read.
Combinations that are refused. Two rules compare one field with another. A request
that breaks either fails with 422 validation_failed, and errors points at the field.
building.building_type must be a type that goes with building.occupancy_type: a
residential occupancy (including residential_manufactured_home) takes a residential
building type, a non-residential occupancy takes a non-residential one (which is where
manufactured_home and travel_trailer belong), and a building type sent with no
occupancy must be a residential type. policy.expiration_date must not be earlier than
policy.effective_date.
Carrier details. The carrier’s details print on the adjuster’s forms. Send them in full: name, phone, email and address.
Retries. Idempotency-Key is required. Retrying the same request (same method, path
and body) with the same key within 24 hours returns the same status code with the claim’s
current state, and creates nothing new. The same key with a different request fails with
422 idempotency_key_reused.
curl --request POST \
--url https://api.osaconnection.com/v1/claims \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"external_id": "CMS-884512",
"claim_number": "FL-2026-0091832",
"adjuster_osa_id": "Xk3pQ9vT2mN8rL5wB7yC1dF4gH6j",
"loss": {
"date": "2026-09-27"
},
"policy": {
"number": "8705123456"
},
"carrier": {
"name": "Gulf Coast Mutual Insurance"
},
"loss_location": {
"street": "418 Bayshore Drive",
"city": "Tampa",
"state": "FL",
"zip": "33606"
},
"policyholder": {
"first_name": "Maria",
"last_name": "Delgado",
"phone": "8135550142"
}
}
'{
"id": "3f8a2c61-5b7e-4d2a-9c1e-7a4b2d9e6f10",
"external_id": "CMS-884512",
"claim_number": "FL-2026-0091832",
"test": false,
"created_at": "2026-09-28T14:32:11Z",
"updated_at": "2026-09-28T14:32:11Z",
"assignment": {
"status": "pending_acceptance",
"adjuster_osa_id": "Xk3pQ9vT2mN8rL5wB7yC1dF4gH6j",
"responded_at": null,
"rejection_reason": null
},
"loss": {
"date": "2026-09-27",
"peril": "flood"
},
"policy": {
"number": "8705123456"
},
"carrier": {
"name": "Gulf Coast Mutual Insurance"
},
"loss_location": {
"street": "418 Bayshore Drive",
"city": "Tampa",
"state": "FL",
"zip": "33606"
},
"policyholder": {
"first_name": "Maria",
"last_name": "Delgado",
"phone": "8135550142"
}
}Authorizations
Send your API key as a bearer token: Authorization: Bearer osa_live_….
Keys are opaque; each belongs to exactly one firm and one purpose. Keys starting with
osa_test_ reach only test claims and test accounts. The scopes listed on each
operation are the permissions the key needs; GET /v1/me shows the ones your key has.
Headers
A unique value your system generates for each operation, such as a UUID. Reuse the same
value only when retrying the same request. The key is matched with a fingerprint of the
whole request: method, path and body. For 24 hours, a retry of the same request with the
same key returns the same status code with the resource's current state, and creates
nothing new; the same key with a different request fails with
422 idempotency_key_reused.
1 - 255Body
The claim, as your claims system knows it at assignment time.
A claim to send to an adjuster.
Your own id for the claim in your system (for example your claims-management record id). Unique within your firm and the key's environment (test or live), and never changed. No leading or trailing whitespace.
1 - 100^\S(.*\S)?$"CMS-884512"
The carrier's claim number. A claim number that matches one of your firm's open claims sent through the API in the same environment (test or live) is rejected as a duplicate. No leading or trailing whitespace.
1 - 100^\S(.*\S)?$"FL-2026-0091832"
The OSAID of the adjuster to send the claim to. They must be an active member of your firm.
1 - 128"Xk3pQ9vT2mN8rL5wB7yC1dF4gH6j"
The loss being claimed.
Show child attributes
Show child attributes
The insurance policy the claim is made under.
Show child attributes
Show child attributes
The insurance carrier. The carrier's details print on the adjuster's forms, so send them in full: name, phone, email and address.
Show child attributes
Show child attributes
The address of the insured property where the loss happened.
Show child attributes
Show child attributes
The policyholder. Send first_name and last_name, or company_name (or all three),
and at least one of phone and email, so the adjuster can make contact.
- Option 1
- Option 2
- Option 3
- Option 4
Show child attributes
Show child attributes
Your firm's file number, shown to the adjuster. external_id is not shown to the
adjuster, so send this when they need a reference of yours.
1 - 100Plain-text notes for the adjuster, shown with the claim in the app.
1 - 4000The date the loss was reported to the carrier.
"2026-09-27"
The date the policyholder was contacted about the claim, when that has already happened (for example on a claim that is being reassigned). The adjuster can change it in the app.
"2026-09-27"
The date of the inspection. It fills the date only and does not create an appointment in the app. The adjuster can change it in the app.
"2026-09-27"
Other people or companies involved in the claim.
20Another person or company involved in the claim. Send a name (first and last, or a company).
- Option 1
- Option 2
Show child attributes
Show child attributes
The insurance agent or agency on the policy.
Show child attributes
Show child attributes
The mortgage company on the property.
Show child attributes
Show child attributes
What you know about the insured building. All optional; the adjuster verifies these on site.
Show child attributes
Show child attributes
Coverage limits and deductibles from the policy.
Show child attributes
Show child attributes
Figures the adjuster's estimate starts from.
Show child attributes
Show child attributes
Response
The claim was created and offered to the adjuster. A retry of the same request with
the same Idempotency-Key returns 201 again, with the claim's current state.
A claim as you sent it, with OSA's id, your external_id, and the current assignment.
Optional fields you didn't send are omitted. Adjusters' later edits in the app don't
change these fields.
OSA's id for the claim.
Your own id for the claim.
The carrier's claim number.
true for a test claim: one sent with a test key to a test account. Test claims are
never billed. The value never changes.
When the claim was created.
When something you can see last changed: creation, an offer, an acceptance or a
rejection. This is the field updated_since filters on.
The latest offer of the claim to an adjuster. When you offer the claim to someone else, this describes the new offer and the earlier response is no longer shown.
Show child attributes
Show child attributes
The loss being claimed.
Show child attributes
Show child attributes
The insurance policy, as you sent it.
Show child attributes
Show child attributes
The insurance carrier, as you sent it.
Show child attributes
Show child attributes
The address of the insured property, as you sent it.
Show child attributes
Show child attributes
The policyholder, as you sent it.
Show child attributes
Show child attributes
Your firm's file number.
Your notes for the adjuster.
The date the loss was reported to the carrier.
The date the policyholder was contacted, as you sent it.
The date of the inspection, as you sent it.
Other people or companies involved in the claim.
Show child attributes
Show child attributes
The agent, as you sent it.
Show child attributes
Show child attributes
The mortgage company, as you sent it.
Show child attributes
Show child attributes
The building details, as you sent them.
Show child attributes
Show child attributes
Coverage limits and deductibles, as you sent them.
Show child attributes
Show child attributes
The estimate figures, as you sent them.
Show child attributes
Show child attributes