> ## Documentation Index > Fetch the complete documentation index at: https://docs.osaconnection.com/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml /openapi.yaml post /v1/claims openapi: 3.1.0 info: title: OSA Partner API version: 1.0.0 summary: Send claims to adjusters in the OSA app and follow their acceptance. description: > The OSA Partner API lets an adjusting firm's claims system invite adjusters to the firm, send them claims, and see whether each claim was accepted or rejected in the OSA app. **Conventions** - All requests and responses are JSON (`application/json`); errors use RFC 9457 problem details (`application/problem+json`). - Field names are `snake_case`. Enum values are lowercase (for example `flood`, `pending_acceptance`), except US state and territory codes, which are the standard two-letter USPS codes, and flood zones, which are written as FEMA writes them (for example `AE`). - Enums are **open**: new values may be added to responses at any time, so your code must tolerate values it doesn't recognise. - Additive changes (new endpoints, new optional request fields, new response fields, new enum values) are made within `/v1`. Breaking changes go to a new version. - Requests are strict: an unknown or misspelled body field or query parameter is rejected with `422 validation_failed`, so typos can't be silently ignored. - Your own claim id (`external_id`) is stored on every claim and returned on every claim response, so you can match claims without keeping OSA's id. - Timestamps are RFC 3339 date-times in UTC. Dates that are calendar dates (such as the date of loss) are `YYYY-MM-DD` and are never converted between time zones. **Keys.** Every request except `GET /v1/health` needs an API key sent as `Authorization: Bearer `. Live keys start with `osa_live_`; test keys start with `osa_test_` and only reach test claims and test accounts. contact: name: OSA API support email: info@osaconnection.com url: https://docs.osaconnection.com servers: - url: https://api.osaconnection.com description: >- Production. Live and test keys both use this host; the key decides which data you reach. security: - apiKey: [] tags: - name: Claims description: > Send claims to adjusters, offer them to another adjuster, and poll for acceptance. `/v1/claims` is always the claims your firm sent through the API. - name: Adjusters description: Invite adjusters to your firm by their OSAID and track their invitations. - name: Account description: Check which firm and permissions your API key carries. - name: Health description: Service availability. No key needed. paths: /v1/claims: post: tags: - Claims summary: Send a claim to an adjuster description: > 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`. operationId: createClaim parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true description: The claim, as your claims system knows it at assignment time. content: application/json: schema: $ref: '#/components/schemas/ClaimCreate' examples: minimal: summary: Only the required fields value: 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' full: summary: A fuller NFIP flood claim value: external_id: CMS-884512 claim_number: FL-2026-0091832 file_number: TPA-55120 adjuster_osa_id: Xk3pQ9vT2mN8rL5wB7yC1dF4gH6j instructions: >- Policyholder is staying with family; call before visiting. Gate code 4471. reported_date: '2026-09-28' contact_date: '2026-09-29' inspection_date: '2026-10-02' loss: date: '2026-09-27' peril: flood policy: number: '8705123456' form: dwelling program: nfip effective_date: '2026-03-15' expiration_date: '2027-03-15' carrier: name: Gulf Coast Mutual Insurance phone: '8005550199' email: claims@gulfcoastmutual.example.com address: street: 2100 Harbour Island Boulevard, Suite 300 city: Tampa state: FL zip: '33602' loss_location: street: 418 Bayshore Drive city: Tampa state: FL zip: '33606' latitude: 27.9312 longitude: -82.4871 policyholder: first_name: Maria last_name: Delgado phone: '8135550142' secondary_phone: '8135550178' email: maria.delgado@example.com mailing_address: street: 1200 W Platt Street, Apt 4 city: Tampa state: FL zip: '33606' additional_contacts: - type: additional_policyholder first_name: Luis last_name: Delgado phone: '8135550143' agent: name: Coastal Insurance Agency phone: '8135550120' email: service@coastal-agency.example.com mortgagee: name: Suncoast Federal Credit Union building: occupancy_type: single_family_home building_type: main_dwelling foundation_type: slab_on_grade number_of_floors: 2 firm_status: post_firm firm_date: '1982-06-18' construction_date: '1996-04-01' flood_zone: AE community_number: '120114' map_panel_number: 12057C0354J construction_type: masonry number_of_units: 1 first_floor_height_feet: 1 first_floor_height_inches: 6 flood_opening_count: 0 coverages: building: limit: 250000 deductible: 2000 contents: limit: 100000 deductible: 2000 special_limits_cap: 2500 estimate: contents_tax_rate: 0.07 responses: '201': description: > 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. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Claim' examples: created: summary: Claim created, waiting for the adjuster value: 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' '400': $ref: '#/components/responses/MalformedRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/DuplicateClaim' '413': $ref: '#/components/responses/PayloadTooLarge' '422': $ref: '#/components/responses/ClaimRequestUnprocessable' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - apiKey: - claims:create components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: true description: > 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`. schema: type: string minLength: 1 maxLength: 255 examples: uuid: summary: A UUID per operation value: 7c4e2b9a-1f3d-4e8a-b6c5-0d9e8f7a6b5c schemas: ClaimCreate: type: object description: A claim to send to an adjuster. additionalProperties: false required: - external_id - claim_number - adjuster_osa_id - loss - policy - carrier - loss_location - policyholder properties: external_id: $ref: '#/components/schemas/ExternalId' claim_number: type: string minLength: 1 maxLength: 100 pattern: ^\S(.*\S)?$ description: > 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. examples: - FL-2026-0091832 file_number: type: string minLength: 1 maxLength: 100 description: > 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. adjuster_osa_id: $ref: '#/components/schemas/OsaId' description: >- The OSAID of the adjuster to send the claim to. They must be an active member of your firm. instructions: type: string minLength: 1 maxLength: 4000 description: Plain-text notes for the adjuster, shown with the claim in the app. reported_date: $ref: '#/components/schemas/CalendarDate' description: The date the loss was reported to the carrier. contact_date: $ref: '#/components/schemas/CalendarDate' description: > 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. inspection_date: $ref: '#/components/schemas/CalendarDate' description: > 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. loss: $ref: '#/components/schemas/Loss' policy: $ref: '#/components/schemas/Policy' carrier: $ref: '#/components/schemas/Carrier' loss_location: $ref: '#/components/schemas/LossLocation' policyholder: $ref: '#/components/schemas/PolicyholderCreate' additional_contacts: type: array description: Other people or companies involved in the claim. maxItems: 20 items: $ref: '#/components/schemas/AdditionalContactCreate' agent: $ref: '#/components/schemas/Agent' mortgagee: $ref: '#/components/schemas/Mortgagee' building: $ref: '#/components/schemas/Building' coverages: $ref: '#/components/schemas/Coverages' estimate: $ref: '#/components/schemas/Estimate' Claim: type: object description: > 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. required: - id - external_id - claim_number - test - created_at - updated_at - assignment - loss - policy - carrier - loss_location - policyholder properties: id: type: string format: uuid description: OSA's id for the claim. external_id: type: string description: Your own id for the claim. claim_number: type: string description: The carrier's claim number. test: type: boolean description: > `true` for a test claim: one sent with a test key to a test account. Test claims are never billed. The value never changes. created_at: type: string format: date-time description: When the claim was created. updated_at: type: string format: date-time description: > When something you can see last changed: creation, an offer, an acceptance or a rejection. This is the field `updated_since` filters on. assignment: $ref: '#/components/schemas/Assignment' file_number: type: string description: Your firm's file number. instructions: type: string description: Your notes for the adjuster. reported_date: type: string format: date description: The date the loss was reported to the carrier. contact_date: type: string format: date description: The date the policyholder was contacted, as you sent it. inspection_date: type: string format: date description: The date of the inspection, as you sent it. loss: $ref: '#/components/schemas/LossOut' policy: $ref: '#/components/schemas/PolicyOut' carrier: $ref: '#/components/schemas/CarrierOut' loss_location: $ref: '#/components/schemas/LossLocationOut' policyholder: $ref: '#/components/schemas/Policyholder' additional_contacts: type: array description: Other people or companies involved in the claim. items: $ref: '#/components/schemas/AdditionalContact' agent: $ref: '#/components/schemas/AgentOut' mortgagee: $ref: '#/components/schemas/MortgageeOut' building: $ref: '#/components/schemas/BuildingOut' coverages: $ref: '#/components/schemas/CoveragesOut' estimate: $ref: '#/components/schemas/EstimateOut' ExternalId: type: string description: > 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. minLength: 1 maxLength: 100 pattern: ^\S(.*\S)?$ examples: - CMS-884512 OsaId: type: string description: > An adjuster's OSAID: their OSA account id. It exists once the adjuster has signed in to the OSA app, and they can read it from the app. minLength: 1 maxLength: 128 examples: - Xk3pQ9vT2mN8rL5wB7yC1dF4gH6j CalendarDate: type: string format: date description: A calendar date, `YYYY-MM-DD`. examples: - '2026-09-27' Loss: type: object description: The loss being claimed. additionalProperties: false required: - date properties: date: type: string format: date description: > The date of loss: the calendar date **at the loss location**, `YYYY-MM-DD`. It is never converted between time zones. Someone in another time zone reporting a Florida loss sends the Florida date, and every adjuster sees that same date. examples: - '2026-09-27' peril: type: string description: >- The cause of loss. `flood` is the only value today; more will be added. enum: - flood default: flood Policy: type: object description: The insurance policy the claim is made under. additionalProperties: false required: - number properties: number: type: string minLength: 1 maxLength: 100 description: The policy number. form: type: string description: > The policy form. `dwelling`: Dwelling Form. `dwelling_gfip`: Dwelling Form (Group Flood Insurance Policy). `general_property`: General Property Form. `rcbap`: Residential Condominium Building Association Policy. enum: - dwelling - dwelling_gfip - general_property - rcbap program: type: string description: >- `nfip`: National Flood Insurance Program. `private`: private flood. `other`: anything else. enum: - nfip - private - other effective_date: $ref: '#/components/schemas/CalendarDate' description: The date the policy term starts. expiration_date: $ref: '#/components/schemas/CalendarDate' description: > The date the policy term ends. It must not be earlier than `effective_date`; a request where it is fails with `422 validation_failed`. The same day is accepted. edn: type: string minLength: 1 maxLength: 50 description: > The Event Designation Number (EDN) of the flood event, as the carrier gives it. Carrier: type: object description: > The insurance carrier. The carrier's details print on the adjuster's forms, so send them in full: name, phone, email and address. additionalProperties: false required: - name properties: name: type: string minLength: 1 maxLength: 255 description: The carrier's name. phone: $ref: '#/components/schemas/Phone' description: The carrier's claims phone number. email: $ref: '#/components/schemas/Email' description: The carrier's claims email address. address: $ref: '#/components/schemas/Address' description: The carrier's mailing address. LossLocation: type: object description: The address of the insured property where the loss happened. additionalProperties: false required: - street - city - state - zip properties: street: type: string minLength: 1 maxLength: 255 description: Street address, including any unit or apartment number. city: type: string minLength: 1 maxLength: 100 description: City. state: $ref: '#/components/schemas/State' zip: $ref: '#/components/schemas/Zip' latitude: type: number minimum: -90 maximum: 90 description: Latitude in decimal degrees. longitude: type: number minimum: -180 maximum: 180 description: Longitude in decimal degrees. PolicyholderCreate: type: object description: > 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. additionalProperties: false properties: first_name: type: string minLength: 1 maxLength: 100 description: First name. last_name: type: string minLength: 1 maxLength: 100 description: Last name. company_name: type: string minLength: 1 maxLength: 255 description: Company name, for policyholders that are businesses or associations. phone: $ref: '#/components/schemas/Phone' description: Primary phone number. secondary_phone: $ref: '#/components/schemas/Phone' description: Another phone number. email: $ref: '#/components/schemas/Email' description: Email address. mailing_address: $ref: '#/components/schemas/Address' description: Mailing address, if different from the loss location. allOf: - anyOf: - required: - first_name - last_name properties: first_name: true last_name: true - required: - company_name properties: company_name: true - anyOf: - required: - phone properties: phone: true - required: - email properties: email: true AdditionalContactCreate: type: object description: >- Another person or company involved in the claim. Send a name (first and last, or a company). additionalProperties: false required: - type properties: type: $ref: '#/components/schemas/ContactType' first_name: type: string minLength: 1 maxLength: 100 description: First name. last_name: type: string minLength: 1 maxLength: 100 description: Last name. company_name: type: string minLength: 1 maxLength: 255 description: Company name. phone: $ref: '#/components/schemas/Phone' description: Primary phone number. secondary_phone: $ref: '#/components/schemas/Phone' description: Another phone number. email: $ref: '#/components/schemas/Email' description: Email address. has_representation_letter: type: boolean description: Whether a letter of representation is on file for this contact. anyOf: - required: - first_name - last_name properties: first_name: true last_name: true - required: - company_name properties: company_name: true Agent: type: object description: The insurance agent or agency on the policy. additionalProperties: false properties: name: type: string minLength: 1 maxLength: 255 description: Agent or agency name. phone: $ref: '#/components/schemas/Phone' description: Phone number. email: $ref: '#/components/schemas/Email' description: Email address. Mortgagee: type: object description: The mortgage company on the property. additionalProperties: false required: - name properties: name: type: string minLength: 1 maxLength: 255 description: Mortgage company name. Building: type: object description: > What you know about the insured building. All optional; the adjuster verifies these on site. additionalProperties: false properties: occupancy_type: type: string description: > The NFIP occupancy type. Only certain pairs of `occupancy_type` and `building_type` are accepted; any other pair is refused with `422 validation_failed`. See `building_type`. enum: - single_family_home - residential_unit - residential_manufactured_home - two_to_four_family_building - residential_condo_building - other_residential_building - non_residential_building - non_residential_unit - non_residential_manufactured_home building_type: type: string description: > The kind of building. Only certain pairs of `occupancy_type` and `building_type` are accepted; any other pair is refused with `422 validation_failed`. The residential types are `main_dwelling`, `detached_guest_house`, `apartment_unit`, `entire_apartment_building`, `cooperative_unit`, `entire_cooperative_building`, `residential_condo_unit_residential`, `residential_condo_unit_non_residential`, `entire_residential_condo_building` and `other_dwelling_type`. The non-residential types are `agricultural_building`, `commercial_building`, `government_owned_building`, `house_of_worship_building`, `recreation_building`, `detached_garage`, `storage_or_tools_shed`, `other_non_residential_type`, `manufactured_home` and `travel_trailer`. A residential occupancy type, including `residential_manufactured_home`, takes a residential type. A non-residential occupancy type (`non_residential_building`, `non_residential_unit` or `non_residential_manufactured_home`) takes a non-residential type, so `manufactured_home` and `travel_trailer` go with the non-residential occupancy types. With no `occupancy_type`, the building type must be a residential type. A later release will also accept `manufactured_home` and `travel_trailer` with `residential_manufactured_home`. enum: - main_dwelling - detached_guest_house - apartment_unit - entire_apartment_building - cooperative_unit - entire_cooperative_building - residential_condo_unit_residential - residential_condo_unit_non_residential - entire_residential_condo_building - other_dwelling_type - agricultural_building - commercial_building - government_owned_building - house_of_worship_building - recreation_building - detached_garage - storage_or_tools_shed - other_non_residential_type - manufactured_home - travel_trailer foundation_type: type: string description: > `slab_on_grade`; `basement` (non-elevated); `crawlspace`; `elevated_no_enclosure` (on piers, posts or piles); `elevated_with_enclosure_open` (enclosure on piers, posts or piles); `elevated_with_enclosure_walls` (enclosure on foundation walls). enum: - slab_on_grade - basement - crawlspace - elevated_no_enclosure - elevated_with_enclosure_open - elevated_with_enclosure_walls number_of_floors: type: integer minimum: 1 maximum: 200 description: Number of floors, including the basement if there is one. firm_status: type: string description: > The building's FIRM status. `pre_firm`: built or substantially improved on or before 31 December 1974, or before the community's initial Flood Insurance Rate Map (FIRM) took effect, whichever is later. `post_firm`: built or substantially improved after that. enum: - pre_firm - post_firm firm_date: $ref: '#/components/schemas/CalendarDate' description: >- The effective date of the community's initial Flood Insurance Rate Map (FIRM). construction_date: $ref: '#/components/schemas/CalendarDate' description: The date the building was built. flood_zone: $ref: '#/components/schemas/FloodZone' description: >- The building's flood zone, written as FEMA writes it (for example `AE`). community_number: type: string minLength: 1 maxLength: 20 description: The NFIP community number from the flood map. examples: - '120114' map_panel_number: type: string minLength: 1 maxLength: 20 description: The flood map panel number. examples: - 12057C0354J construction_type: type: string description: How the building is built. `framed`, `masonry` or `other`. enum: - framed - masonry - other number_of_units: type: integer minimum: 1 maximum: 100000 description: Number of units in the building. first_floor_height_feet: type: integer minimum: 0 maximum: 1000 description: | The first floor height, whole feet. Send the remaining inches in `first_floor_height_inches`. first_floor_height_inches: type: integer minimum: 0 maximum: 11 description: The inches part of the first floor height, 0 to 11. flood_opening_count: type: integer minimum: 0 maximum: 100000 description: Number of flood openings in the building. Coverages: type: object description: Coverage limits and deductibles from the policy. additionalProperties: false properties: building: $ref: '#/components/schemas/CoverageAmounts' description: Building property coverage (NFIP Coverage A). contents: $ref: '#/components/schemas/CoverageAmounts' description: Personal property coverage (NFIP Coverage B). other: $ref: '#/components/schemas/CoverageAmounts' description: > Coverage for anything not covered under the building or contents coverage. special_limits_cap: $ref: '#/components/schemas/Money' description: > The cap on special limits items, in US dollars. When you send nothing, the app uses the NFIP standard of $2,500. Estimate: type: object description: Figures the adjuster's estimate starts from. additionalProperties: false properties: contents_tax_rate: type: number minimum: 0 maximum: 1 description: The tax rate for contents, as a fraction. `0.07` means 7%. examples: - 0.07 Assignment: type: object description: > 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. required: - status - adjuster_osa_id - responded_at - rejection_reason properties: status: $ref: '#/components/schemas/AssignmentStatus' adjuster_osa_id: type: - string - 'null' description: > The adjuster the claim was offered to. On a rejected claim, this is the adjuster who rejected it. `null` when the claim isn't currently offered to anyone (`unassigned`). responded_at: type: - string - 'null' format: date-time description: >- When the adjuster accepted or rejected the claim; `null` while pending. rejection_reason: type: - string - 'null' description: >- The reason the adjuster gave for rejecting, if any. `null` unless rejected; optional even then. LossOut: type: object description: The loss being claimed. required: - date - peril properties: date: type: string format: date description: The date of loss at the loss location, exactly as you sent it. peril: type: string description: The cause of loss. enum: - flood PolicyOut: type: object description: The insurance policy, as you sent it. required: - number properties: number: type: string description: The policy number. form: type: string description: The policy form. enum: - dwelling - dwelling_gfip - general_property - rcbap program: type: string description: The policy program. enum: - nfip - private - other effective_date: type: string format: date description: The date the policy term starts. expiration_date: type: string format: date description: The date the policy term ends. edn: type: string description: >- The Event Designation Number (EDN) of the flood event, as you sent it. CarrierOut: type: object description: The insurance carrier, as you sent it. required: - name properties: name: type: string description: The carrier's name. phone: type: string description: The carrier's claims phone number. email: type: string description: The carrier's claims email address. address: $ref: '#/components/schemas/AddressOut' description: The carrier's mailing address. LossLocationOut: type: object description: The address of the insured property, as you sent it. required: - street - city - state - zip properties: street: type: string description: Street address. city: type: string description: City. state: $ref: '#/components/schemas/State' zip: type: string description: ZIP code. latitude: type: number description: Latitude, if you sent it. longitude: type: number description: Longitude, if you sent it. Policyholder: type: object description: The policyholder, as you sent it. properties: first_name: type: string description: First name. last_name: type: string description: Last name. company_name: type: string description: Company name. phone: type: string description: Primary phone number. secondary_phone: type: string description: Another phone number. email: type: string description: Email address. mailing_address: $ref: '#/components/schemas/AddressOut' description: Mailing address. AdditionalContact: type: object description: Another person or company involved in the claim, as you sent it. required: - type properties: type: $ref: '#/components/schemas/ContactType' first_name: type: string description: First name. last_name: type: string description: Last name. company_name: type: string description: Company name. phone: type: string description: Primary phone number. secondary_phone: type: string description: Another phone number. email: type: string description: Email address. has_representation_letter: type: boolean description: Whether a letter of representation is on file for this contact. AgentOut: type: object description: The agent, as you sent it. properties: name: type: string description: Agent or agency name. phone: type: string description: Phone number. email: type: string description: Email address. MortgageeOut: type: object description: The mortgage company, as you sent it. required: - name properties: name: type: string description: Mortgage company name. BuildingOut: type: object description: The building details, as you sent them. properties: occupancy_type: type: string description: The NFIP occupancy type. enum: - single_family_home - residential_unit - residential_manufactured_home - two_to_four_family_building - residential_condo_building - other_residential_building - non_residential_building - non_residential_unit - non_residential_manufactured_home building_type: type: string description: The kind of building. enum: - main_dwelling - detached_guest_house - apartment_unit - entire_apartment_building - cooperative_unit - entire_cooperative_building - residential_condo_unit_residential - residential_condo_unit_non_residential - entire_residential_condo_building - other_dwelling_type - agricultural_building - commercial_building - government_owned_building - house_of_worship_building - recreation_building - detached_garage - storage_or_tools_shed - other_non_residential_type - manufactured_home - travel_trailer foundation_type: type: string description: The foundation type. enum: - slab_on_grade - basement - crawlspace - elevated_no_enclosure - elevated_with_enclosure_open - elevated_with_enclosure_walls number_of_floors: type: integer description: Number of floors. firm_status: type: string description: > The building's FIRM status. `pre_firm`: built or substantially improved on or before 31 December 1974, or before the community's initial Flood Insurance Rate Map (FIRM) took effect, whichever is later. `post_firm`: built or substantially improved after that. enum: - pre_firm - post_firm firm_date: type: string format: date description: >- The effective date of the community's initial Flood Insurance Rate Map (FIRM). construction_date: type: string format: date description: The date the building was built. flood_zone: $ref: '#/components/schemas/FloodZone' description: The building's flood zone. community_number: type: string description: The NFIP community number. map_panel_number: type: string description: The flood map panel number. construction_type: type: string description: How the building is built. enum: - framed - masonry - other number_of_units: type: integer description: Number of units. first_floor_height_feet: type: integer description: The first floor height, whole feet. first_floor_height_inches: type: integer description: The inches part of the first floor height. flood_opening_count: type: integer description: Number of flood openings. CoveragesOut: type: object description: Coverage limits and deductibles, as you sent them. properties: building: $ref: '#/components/schemas/CoverageAmountsOut' description: Building property coverage (NFIP Coverage A). contents: $ref: '#/components/schemas/CoverageAmountsOut' description: Personal property coverage (NFIP Coverage B). other: $ref: '#/components/schemas/CoverageAmountsOut' description: >- Coverage for anything not covered under the building or contents coverage, as you sent it. special_limits_cap: type: number description: The cap on special limits items, in US dollars. EstimateOut: type: object description: The estimate figures, as you sent them. properties: contents_tax_rate: type: number description: The tax rate for contents, as a fraction. `0.07` means 7%. Problem: type: object description: > An RFC 9457 problem details object. Match on `code`, which is stable; `title` and `detail` are for people and may change. Quote `request_id` when contacting support. required: - type - title - status - detail - code - request_id properties: type: type: string format: uri description: A link to this error's documentation. title: type: string description: A short summary of the error. status: type: integer description: The HTTP status code. detail: type: string description: What went wrong in this request. code: type: string description: > The stable error code. `malformed_request` (400); `invalid_key` (401); `insufficient_scope`, `not_in_plan` (403); `not_found` (404); `duplicate_claim`, `claim_already_accepted`, `already_member`, `invitation_pending` (409); `payload_too_large` (413); `validation_failed`, `idempotency_key_reused`, `unknown_osaid`, `adjuster_not_in_firm`, `adjuster_not_accepting`, `environment_mismatch` (422); `rate_limited` (429); `internal_error` (500). New codes may be added. enum: - malformed_request - invalid_key - insufficient_scope - not_in_plan - not_found - duplicate_claim - claim_already_accepted - already_member - invitation_pending - payload_too_large - validation_failed - idempotency_key_reused - unknown_osaid - adjuster_not_in_firm - adjuster_not_accepting - environment_mismatch - rate_limited - internal_error request_id: type: string description: The id of this request. Quote it when contacting support. errors: type: array description: For `validation_failed`, each invalid field, parameter or header. items: type: object description: >- One problem. Exactly one of `pointer`, `parameter` or `header` says where. required: - detail properties: pointer: type: string description: >- JSON Pointer to a body field, for example `/loss/date`. Empty for the whole body. parameter: type: string description: The name of a query or path parameter, for example `limit`. header: type: string description: The name of a request header, for example `Idempotency-Key`. detail: type: string description: What is wrong with it. existing_claim_id: type: string format: uuid description: >- For `duplicate_claim`, the id of the claim that already exists. Always a claim your key can read. existing_claim_url: type: string format: uri description: >- For `duplicate_claim`, the API link to the claim that already exists. Always a claim your key can read. Phone: type: string description: A phone number. US numbers are usually sent as 10 digits. minLength: 1 maxLength: 20 examples: - '8135550142' Email: type: string format: email maxLength: 255 description: An email address. examples: - maria.delgado@example.com Address: type: object description: A US postal address. additionalProperties: false required: - street - city - state - zip properties: street: type: string minLength: 1 maxLength: 255 description: Street address, including any unit or apartment number. city: type: string minLength: 1 maxLength: 100 description: City. state: $ref: '#/components/schemas/State' zip: $ref: '#/components/schemas/Zip' State: type: string description: > Two-letter USPS code: the 50 states, `DC`, and the US territories `AS` (American Samoa), `GU` (Guam), `MP` (Northern Mariana Islands), `PR` (Puerto Rico) and `VI` (US Virgin Islands). enum: - AL - AK - AZ - AR - CA - CO - CT - DE - DC - FL - GA - HI - ID - IL - IN - IA - KS - KY - LA - ME - MD - MA - MI - MN - MS - MO - MT - NE - NV - NH - NJ - NM - NY - NC - ND - OH - OK - OR - PA - RI - SC - SD - TN - TX - UT - VT - VA - WA - WV - WI - WY - AS - GU - MP - PR - VI examples: - FL Zip: type: string description: Five-digit ZIP code, optionally ZIP+4. pattern: ^\d{5}(-\d{4})?$ examples: - '33606' - 33606-1234 ContactType: type: string description: > The contact's relationship to the claim. `additional_policyholder`, `law_firm`, `power_of_attorney`, `principal`, `relative`, `translator` or `other`. enum: - additional_policyholder - law_firm - power_of_attorney - principal - relative - translator - other FloodZone: type: string description: > A flood zone from the Flood Insurance Rate Map, written as FEMA writes it: `A`, `AE`, `A1` to `A30`, `A99`, `AH`, `AO`, `AR`, `V`, `VE`, `V1` to `V30`, `B`, `C`, `D` and `X`. enum: - A - AE - A1 - A2 - A3 - A4 - A5 - A6 - A7 - A8 - A9 - A10 - A11 - A12 - A13 - A14 - A15 - A16 - A17 - A18 - A19 - A20 - A21 - A22 - A23 - A24 - A25 - A26 - A27 - A28 - A29 - A30 - A99 - AH - AO - AR - V - VE - V1 - V2 - V3 - V4 - V5 - V6 - V7 - V8 - V9 - V10 - V11 - V12 - V13 - V14 - V15 - V16 - V17 - V18 - V19 - V20 - V21 - V22 - V23 - V24 - V25 - V26 - V27 - V28 - V29 - V30 - B - C - D - X examples: - AE - X CoverageAmounts: type: object description: A coverage limit and its deductible. additionalProperties: false properties: limit: $ref: '#/components/schemas/Money' description: The coverage limit, in US dollars. deductible: $ref: '#/components/schemas/Money' description: The deductible, in US dollars. Money: type: number minimum: 0 description: An amount in US dollars and cents. examples: - 250000 - 1250.5 AssignmentStatus: type: string description: > Where the latest offer stands. `pending_acceptance`: the adjuster hasn't answered yet. `accepted`: the adjuster accepted the claim. `rejected`: the adjuster rejected it; you can offer it to another adjuster. `unassigned`: the claim isn't currently offered to anyone; you can offer it to an adjuster. enum: - pending_acceptance - accepted - rejected - unassigned examples: - pending_acceptance AddressOut: type: object description: A US postal address. required: - street - city - state - zip properties: street: type: string description: Street address. city: type: string description: City. state: $ref: '#/components/schemas/State' zip: type: string description: ZIP code. CoverageAmountsOut: type: object description: A coverage limit and its deductible. properties: limit: type: number description: The coverage limit, in US dollars. deductible: type: number description: The deductible, in US dollars. headers: RequestId: description: > The id of this request. Quote it to OSA support. On error responses it equals `request_id` in the body. required: true schema: type: string examples: request_id: summary: A request id value: 7f3e9a1c2b4d6e8f0a1b3c5d7e9f1a2b RetryAfter: description: Seconds to wait before retrying. required: true schema: type: integer minimum: 1 examples: seconds: summary: Retry in 12 seconds value: 12 responses: MalformedRequest: description: The body isn't valid JSON or can't be read (`malformed_request`). headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: malformed_request: summary: malformed_request value: type: https://docs.osaconnection.com/errors#malformed_request title: Malformed request status: 400 detail: The request body isn't valid JSON. code: malformed_request request_id: 0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d Unauthorized: description: > The key is missing, malformed, unknown, revoked or expired (`invalid_key`). headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: invalid_key: summary: invalid_key value: type: https://docs.osaconnection.com/errors#invalid_key title: Invalid API key status: 401 detail: The API key is missing, malformed, revoked or expired. code: invalid_key request_id: 7f3e9a1c2b4d6e8f0a1b3c5d7e9f1a2b Forbidden: description: > The key is valid but can't do this. `insufficient_scope`: the key's purpose doesn't include the permission this operation needs. `not_in_plan`: your firm's plan doesn't include it. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: insufficient_scope: summary: insufficient_scope value: type: https://docs.osaconnection.com/errors#insufficient_scope title: Insufficient scope status: 403 detail: This key doesn't have the claims:write permission. code: insufficient_scope request_id: 0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e not_in_plan: summary: not_in_plan value: type: https://docs.osaconnection.com/errors#not_in_plan title: Not in plan status: 403 detail: Your firm's plan doesn't include adjuster invitations. code: not_in_plan request_id: 1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f DuplicateClaim: description: > The claim already exists (`duplicate_claim`). In the key's environment (test or live), your firm already has a claim with this `external_id`, or an open claim sent through the API with this `claim_number`. Test and live claims never collide. `existing_claim_id` and `existing_claim_url` always point to a claim your key can read. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: duplicate_claim: summary: duplicate_claim value: type: https://docs.osaconnection.com/errors#duplicate_claim title: Duplicate claim status: 409 detail: Your firm already has a claim with external_id CMS-884512. code: duplicate_claim request_id: 3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b existing_claim_id: 3f8a2c61-5b7e-4d2a-9c1e-7a4b2d9e6f10 existing_claim_url: >- https://api.osaconnection.com/v1/claims/3f8a2c61-5b7e-4d2a-9c1e-7a4b2d9e6f10 PayloadTooLarge: description: The body is larger than 1 MB (`payload_too_large`). headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: payload_too_large: summary: payload_too_large value: type: https://docs.osaconnection.com/errors#payload_too_large title: Payload too large status: 413 detail: Request bodies are limited to 1 MB. code: payload_too_large request_id: 1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e ClaimRequestUnprocessable: description: > The claim can't be created. `validation_failed`: the request is invalid (see `errors`). `idempotency_key_reused`: the `Idempotency-Key` was already used with a different request. `unknown_osaid`: OSA doesn't know this OSAID. `adjuster_not_in_firm`: the adjuster isn't an active member of your firm (real adjusters are invisible to test keys, so a test key naming one gets this too). `adjuster_not_accepting`: the adjuster lacks the permission to accept claims or has paused assignments. `environment_mismatch`: a live key named a test account. `validation_failed` also covers the two rules that compare one field with another: a `building.building_type` that doesn't go with `building.occupancy_type` (or, when no occupancy is sent, isn't a residential type), and a `policy.expiration_date` earlier than `policy.effective_date`. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: validation_failed: summary: validation_failed value: type: https://docs.osaconnection.com/errors#validation_failed title: Validation failed status: 422 detail: The request has 2 invalid fields. code: validation_failed request_id: 9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b errors: - pointer: /loss/date detail: must match format "date" - pointer: /loss_location detail: must NOT have additional properties (zipcode) validation_failed_building_pair: summary: >- validation_failed (building type doesn't go with the occupancy type) value: type: https://docs.osaconnection.com/errors#validation_failed title: Validation failed status: 422 detail: The request has 1 invalid field. code: validation_failed request_id: 5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f errors: - pointer: /building/building_type detail: >- must be a residential building type when occupancy_type is single_family_home validation_failed_policy_dates: summary: validation_failed (policy ends before it starts) value: type: https://docs.osaconnection.com/errors#validation_failed title: Validation failed status: 422 detail: The request has 1 invalid field. code: validation_failed request_id: 6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a errors: - pointer: /policy/expiration_date detail: must not be earlier than effective_date validation_failed_whitespace: summary: validation_failed (leading or trailing spaces) value: type: https://docs.osaconnection.com/errors#validation_failed title: Validation failed status: 422 detail: The request has 1 invalid field. code: validation_failed request_id: 4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d errors: - pointer: /external_id detail: must not start or end with whitespace missing_idempotency_key: summary: validation_failed (missing Idempotency-Key) value: type: https://docs.osaconnection.com/errors#validation_failed title: Validation failed status: 422 detail: The Idempotency-Key header is required. code: validation_failed request_id: 5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e errors: - header: Idempotency-Key detail: is required idempotency_key_reused: summary: idempotency_key_reused value: type: https://docs.osaconnection.com/errors#idempotency_key_reused title: Idempotency key reused status: 422 detail: >- This Idempotency-Key was already used with a different request. code: idempotency_key_reused request_id: 6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f unknown_osaid: summary: unknown_osaid value: type: https://docs.osaconnection.com/errors#unknown_osaid title: Unknown OSAID status: 422 detail: No OSA user has this OSAID. code: unknown_osaid request_id: 0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c adjuster_not_in_firm: summary: adjuster_not_in_firm value: type: https://docs.osaconnection.com/errors#adjuster_not_in_firm title: Adjuster not in firm status: 422 detail: >- This adjuster isn't an active member of your firm. Invite them first. code: adjuster_not_in_firm request_id: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d adjuster_not_accepting: summary: adjuster_not_accepting value: type: https://docs.osaconnection.com/errors#adjuster_not_accepting title: Adjuster not accepting claims status: 422 detail: This adjuster isn't accepting claim assignments right now. code: adjuster_not_accepting request_id: 2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e environment_mismatch: summary: environment_mismatch value: type: https://docs.osaconnection.com/errors#environment_mismatch title: Environment mismatch status: 422 detail: Live keys can't send claims to test accounts. code: environment_mismatch request_id: 7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a RateLimited: description: > Too many requests for this key (`rate_limited`). Wait for the number of seconds in `Retry-After`, then retry. headers: Retry-After: $ref: '#/components/headers/RetryAfter' X-Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: rate_limited: summary: rate_limited value: type: https://docs.osaconnection.com/errors#rate_limited title: Rate limited status: 429 detail: This key has exceeded 300 requests per minute. code: rate_limited request_id: 9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f InternalError: description: > Something failed on OSA's side (`internal_error`). Retry with exponential backoff; for `POST` requests, reuse the same `Idempotency-Key`. If it persists, contact OSA with the `request_id`. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: internal_error: summary: internal_error value: type: https://docs.osaconnection.com/errors#internal_error title: Internal error status: 500 detail: Something went wrong on our side. Retry later. code: internal_error request_id: 2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f securitySchemes: apiKey: type: http scheme: bearer bearerFormat: osa_live_… or osa_test_… description: > 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.