Skip to main content

Quickstart

This quickstart walks through the happy-path integration loop: obtain a token, look up a beneficiary, initiate a pre-authorization request for a medication, attach the indication, and complete it. By the end you'll have:

  1. A valid sandbox access_token cached locally.
  2. A beneficiary_id you can address in subsequent calls.
  3. An authorization_request_id for the request you initiated.
  4. One or more authorization_code values returned after completing the request.

Same pattern applies to labs, imaging, in-clinic procedures — the difference is only the product codes and the sponsor rules.

Prerequisites​

  1. 1Sandbox credentials from OSIGU

    You need client_id, client_secret, and a provider_slug already attached to your OAuth client. Get them from OSIGU's onboarding team.

  2. 2At least one sponsor slug you can operate under

    OSIGU wires which sponsors your provider is affiliated with. Ask onboarding for a sandbox sponsor_slug — usually there's a mock sponsor called something like sponsor-sandbox or demo-insurer.

  3. 3A test beneficiary in that sponsor's sandbox

    OSIGU seeds test beneficiaries per sandbox sponsor. Ask for a beneficiary's search input values (typically a document number).

1. Get an access token​

OAuth2 client-credentials grant against the OSIGU SSO server:

curl -X POST https://sandbox.osigu.com/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "arc:read arc:write dispensing:read dispensing:write"
}

Cache the access_token for ~50 minutes. Don't fetch a fresh one per request — the auth server rate-limits clients that do.

export TOKEN="eyJhbGciOiJSUzI1NiIs..."

2. Look up the beneficiary​

Before you can request an authorization, you need to identify the beneficiary in the sponsor's directory. The sponsor's search form varies — first list it:

curl "https://sandbox.osigu.com/v1/sponsors/$SPONSOR_SLUG/forms" \
  -H "Authorization: Bearer $TOKEN"

You'll get back the fields the sponsor requires (e.g. document_type + document_number, or member_id + birthdate). Fill them in and search:

curl -X POST "https://sandbox.osigu.com/v1/sponsors/$SPONSOR_SLUG/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "CC",
    "document_number": "123456789"
  }'

Response includes the beneficiary and their active coverage:

{
  "beneficiary_id": "bnf_01HW8GQ2KMNP3F4R5T6Y7U8I9O",
  "first_name": "MARIA",
  "last_name": "GONZALEZ",
  "coverage": {
    "plan_code": "GOLD-100",
    "active": true,
    "effective_until": "2027-01-31"
  }
}

Persist the beneficiary_id — you'll pass it in subsequent calls.

3. Initiate a pre-authorization request​

An authorization request is the initial submission that will produce one or more actual authorizations (grouped per product type according to sponsor rules).

curl -X POST "https://sandbox.osigu.com/arc/v1/authorization-requests" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiary_id": "bnf_01HW8GQ2KMNP3F4R5T6Y7U8I9O",
    "sponsor_slug": "sponsor-sandbox",
    "diagnosis_code": "R51",
    "products": [
      {
        "product_code": "MED-042",
        "product_type": "MEDICATION",
        "quantity": 30,
        "posology": "1 tablet every 8h for 10 days"
      }
    ]
  }'

Response (202 Accepted):

{
  "authorization_request_id": "areq_01HX9KP7VQ2D4FZ8N0YPRQAW6X",
  "status": "PENDING_INDICATION",
  "created_at": "2026-06-25T14:02:11.789Z"
}

The status PENDING_INDICATION means the sponsor needs the medical indication document before it can process the request.

4. Attach the indication​

Most sponsors require a signed prescription or referral. Upload it as multipart:

curl -X POST "https://sandbox.osigu.com/arc/v1/authorization-requests/areq_01HX9KP7VQ2D4FZ8N0YPRQAW6X/upload/files" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@./indication.pdf" \
  -F "file_type=MEDICAL_INDICATION"

Response (204 No Content). The file is now attached to the request.

Don't need multipart? Use the Base64 variant attachAuthorizationIndicationBase64 — same effect, JSON body.

5. Complete the request​

Signal Osigu that the request is ready for processing:

curl -X POST "https://sandbox.osigu.com/arc/v1/authorization-requests/areq_01HX9KP7VQ2D4FZ8N0YPRQAW6X/complete" \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK) includes the resulting authorization(s):

{
  "authorization_request_id": "areq_01HX9KP7VQ2D4FZ8N0YPRQAW6X",
  "status": "COMPLETED",
  "authorizations": [
    {
      "authorization_code": "AUTH-2026-001234",
      "product_type": "MEDICATION",
      "status": "APPROVED",
      "expires_at": "2026-07-25T00:00:00Z"
    }
  ]
}

Some sponsors process synchronously (as above); others accept the request and process asynchronously — you'll receive a webhook when the authorization is issued or rejected. See Webhook events.

6. What to do next​

You've completed the pre-authorization loop. From here:

Troubleshooting​

SymptomLikely cause
401 Unauthorized on /oauth/tokenWrong client_id/client_secret, or hitting the wrong environment's OAuth URL.
403 Forbidden on beneficiary searchYour provider is not affiliated with that sponsor. Confirm with OSIGU support.
404 on beneficiary searchBeneficiary not found in the sponsor's directory, or coverage inactive.
422 Validation error on the request POSTMissing required fields for that sponsor. Check the getSponsorConfiguration response for what the sponsor requires.
Request stuck in PENDING_INDICATION after complete callThe indication file wasn't attached, or it was attached but the sponsor requires a specific file_type. Check getAuthorizationDocumentPolicy for the required types.
Authorization returned but marked REJECTEDThe sponsor evaluated the request and denied it. The response includes a rejection_reason — surface it to the end user.

Stuck? Email support@osigu.com with your authorization_request_id — we can trace the sponsor exchange.