# API 💻

## Postman Collection

[![](https://run.pstmn.io/button.svg)](https://www.postman.com/cardscan/workspace/cardscan-workspace/collection/17501274-09778b26-c4e7-47af-bec2-a338f8b38f57?action=share\&creator=17501274)

## OpenAPI Specification

The complete OpenAPI 3.0 specification for the CardScan API is available at:

<https://github.com/CardScan-ai/api-clients/blob/main/openapi.yaml>

Use this specification to:

* Generate API clients in any language
* Import into API testing tools
* View detailed schema definitions
* Integrate with development tools

## Testing vs Production

After creating an account you can access the test API endpoints on our sandbox server:

{% embed url="<https://sandbox.cardscan.ai>" %}

This endpoint is identical to our production endpoint but **does not allow PHI** and only returns dummy card results.

Once you have signed our **Business Associate Agreement (BAA)** you will be able to access the production server:

{% embed url="<https://api.cardscan.ai>" %}

## Admin Endpoints

The admin endpoints are designed for managing access tokens within our system. These endpoints can only be called using a valid API key. They provide a secure way to generate and manage tokens, ensuring that only authorized users can access sensitive data and functionalities.

### Get Access Token

<mark style="color:blue;">`GET`</mark> `https://sandbox.cardscan.ai/v1/access-token`

This endpoint generates the JSON Web Token (JWT) for a web or mobile user

#### Query Parameters

| Name     | Type   | Description                    |
| -------- | ------ | ------------------------------ |
| user\_id | String | Unique identifier for the user |

{% tabs %}
{% tab title="200" %}

```json
{
  "IdentityId": "us-east-1:0236cb77-ac53-460d-ba39-60b186af2897",
  "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unknown authorization error - please check your token format and try again", 
  "type": "Unauthorized",
  "code":401 
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "API Key is not registered",
  "type": "Unauthorized",
  "code": 401
}
```

{% endtab %}
{% endtabs %}

This endpoint generates a short-lived session token that the web/mobile user will use to directly authenticate with CardScan's servers. See the [Authentication](https://docs.cardscan.ai/authentication#end-user) page for more details.

{% hint style="danger" %}
This function takes an optional `user_id` which **must be unique** between your users.
{% endhint %}

See [Authentication](https://docs.cardscan.ai/authentication#end-user) for code examples.

***

## Insurance Card Scanning Endpoints

### Create Card

<mark style="color:green;">`POST`</mark> `https://sandbox.cardscan.ai/v1/cards`

Creates a card object to initiate the scanning process and will be used for generating upload endpoints.

#### Request Body

| Name                   | Type    | Description                                                                                                                                          |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| enable\_backside\_scan | boolean | <p>Enabled scanning of both sides of the insurance cards. Important for eligibility checks and prior auth.</p><p><strong>Default</strong>: False</p> |
| enable\_livescan       | boolean | <p>Allows the card to process multiple updates per side. Required for live scanning.</p><p><strong>Default</strong>: False</p>                       |

{% tabs %}
{% tab title="201: Created Successful Operation" %}

```json
{
    "card_id": "171d11c4-9154-4f2f-b4ca-0fb610abe05e",
    "state": "pending",
    "created_at": "2024-02-05 15:50:14.856792"
}
```

{% endtab %}

{% tab title="400: Bad Request Bad Request" %}

```json
{
    "message": "enable_backside_scan must be a boolean",
    "type": "Bad Request",
    "code": 400
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --location 'https://sandbox.cardscan.ai/v1/cards' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer endusertokenXXX' \
--data '{
    "enable_backside_scan": true
}'
```

{% endtab %}
{% endtabs %}

### Generate Upload Url

<mark style="color:green;">`POST`</mark> `https://sandbox.cardscan.ai/v1/cards/:card_id/generate-upload-url`

Generates a URL and signed payload to enable direct image upload to AWS S3.

#### Path Parameters

| Name                                       | Type | Description                                  |
| ------------------------------------------ | ---- | -------------------------------------------- |
| card\_id<mark style="color:red;">\*</mark> | UUID | For the card entity to link the upload with. |

#### Request Body

| Name                                          | Type | Description                                                                                                                                                                                                                                   |
| --------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| orientation<mark style="color:red;">\*</mark> | Enum | <p>'<strong>front</strong>' - the front face of the insurance card, often containing the name, member\_id, etc.</p><p>'<strong>back</strong>' - the back side of the card, often containing the claims address, and various phone number.</p> |

{% tabs %}
{% tab title="200 Successful Operation" %}

```javascript
{
  "card_id": "4c901279-622f-485f-85cc-aad1f12c2d8e",
  "upload_url": "https://cardscan-sandbox.s3.amazonaws.com/",
  "upload_parameters": {
    "key": "4c901279-622f-485f-85cc-aad1f12c2d8e",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-security-token": "BADCAFEb3JpZ2sddsfdsfrIAiACLcnulBVymY22qkf3M8XDvlhXweRzDe8V95X73BextSqDAgiU//////////8BEAAaDDUzNTc5NTY3OTQ2NiIM1ZoFizA0PWXBXfiWKtcBVOcw4ss3VbqdPFO7OTJmxuPLUnPKNbsMaRF5sNEsqecP74+mucNgjAwigvQM3K0Bb/WqTsmGIkGXT7p+St1XpyB9nY+nVE1cVgtkggwU4UDXhBpnZLhQIE5fLjEBU+X0Gwd7WVXJdwXFa5iD+EwsQU2aJihBc1tdxYXmIZIkMQ1UXdFPbRc1vX4wcDgzrfbvT5749d1rOh5u9mKxTNc7z/1G4aYswrODlh5N/hSamcKGlaC/wwxrv8gwY64QEp/nQkUuTdrKPSrQRUb7Z5Fj7m8erRixTtYI2rOfAl5Cl",
    "x-amz-credential": "FAKEKEYSDONOTUSEXZYABC/20210413/us-east-1/s3/aws4_request",
    "x-amz-date": "20210413T210019Z",
    "policy": "eyJleHBpcmF0aW9uIjogIjIwMjEtMDQtMTNUMjI6MDA6MTlaIiwgImNvbmRpdGlvbnMiOiBbeyJidWNrZXQiOiAiY2FyZHNjYW4tc2FuZGJveCJ9LCB7ImtleSI6ICI0YzkwMTI3OS02MjJmLTQ4NWYtODVjYy1hYWQxZjEyYzJkOGUifSwgeyJ4LWFtei1hbGdvcml0aG0iOiAiQVdTNC1ITUFDLVNIQTI1NiJ9LCB7IngtYW16LWNyZWRlbnRpYWwiOiAiQUtJSEFMUk9CSVZGTkZYWllBQkMvMjAyMTA0MTMvdXMtZWFzdC0xL3MzL2F3czRfcmVxdWVzdCJ9LCB7IngtYW16LWRhdGUiOiAiMjAyMTA0MTNUMjEwMDE5WiJ9XX0=",
    "x-amz-signature": "40da5a6814f646d9ded38539e37d6badcafe808494b04c76d37ccc89a3e5d34d"
  }
}
```

{% endtab %}

{% tab title="400 Invalid parameters" %}

```javascript
{
    "message": "expiration must be between 100 and 3600",
    "type": "Bad Request",
    "code": 400
}
```

{% endtab %}

{% tab title="401 Missing token or other error" %}

```javascript
{
    "message": "Unknown authorization error - please check your token format and try again",
    "type": "Unauthorized",
    "code": 401
}
```

{% endtab %}

{% tab title="403 Bad or expired token" %}

```javascript
{
    "message": "Token is expired",
    "type": "Authentication Timeout",
    "code": 419
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
The S3 URL only supports HTTP **POSTs**, not PUTs.
{% endhint %}

The `upload_parameters` may change at any time, please make sure to not hardcode the list in any POST command.

{% tabs %}
{% tab title="Curl" %}

```bash
curl --location 'https://sandbox.cardscan.ai/v1/cards/9d709b16-3807-4fc9-b176-4409241beab5/generate-upload-url' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer endusertokenXXX \
--data '{   
    "orientation": "back"
}'
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
// The JS client wraps generate-upload-url in with the file upload functionality.

const client = new CardScanApi({
    sessionToken:token, 
    live: false
});

client.uploadCardImage(file)
.then((cardId) => {
    //update UI.
})
.catch((error) => {
    //retry or update UI
});
```

{% endtab %}

{% tab title="Swift" %}

```swift
// The swift client wraps generate-upload-url with the file upload functionality.

let apiClient = CardScanAPIClient(userToken: userToken, live: false)

apiClient.uploadCardImage(image: image) { result in
    switch result {
    case .failure(let error):
        //check error, retry, update UI.
        print("uploadCardImage error \(error)")
    case .success(let cardId):
        //update UI for success!
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Image uploads have a **maximum** size of 50MB and a **minimum** of 5KB.
{% endhint %}

### List Scanned Cards

<mark style="color:blue;">`GET`</mark> `https://sandbox.cardscan.ai/v1/cards`

#### Query Parameters

| Name   | Type    | Description                                                                                         |
| ------ | ------- | --------------------------------------------------------------------------------------------------- |
| cursor | string  | Used to paginate through results when count is greater that limit.                                  |
| limit  | integer | <p>Count of cards to return.</p><p><strong>Default</strong>: 50</p><p><strong>Max:</strong> 200</p> |

{% tabs %}
{% tab title="200 Successful Response" %}

```javascript
{
    "cards": [
        {
            "card_id": "1bab2f3c-cfbe-4f22-b480-b389ece57f7e",
            "state": "pending",
            "created_at": "2021-07-30 19:56:40.638894+00:00",
        },
        {
            "card_id": "98405a1e-b367-4b3a-876a-e7886b7e1b69",
            "state": "processing",
            "created_at": "2021-07-30 20:26:40.838094+00:00",
        },
        {
            "card_id": "4c901279-622f-485f-85cc-aad1f12c2d8e",
            "state": "error",
            "created_at": "2021-07-30 20:58:50.334343+00:00",
            "error_message": "Failure during OCR process - [E507]"
        },
        {
            "card_id": "a1d743ee-3bb9-468d-a2c5-4e33fa0e1c6e",
            "state": "completed",
            "created_at": "2021-07-31 18:36:33.567313+00:00",
            "details": {
                "group_number": {
                    "value": "98755",
                    "scores": [
                        "0.9994",
                        "0.9828"
                    ]
                },
                "member_number": {
                    "value": "128845682",
                    "scores": [
                        "0.9984",
                        "0.9618"
                    ]
                },
                "member_name": {
                    "value": "emily dickinson",
                    "scores": [
                        "0.9974",
                        "0.8879"
                    ]
                },
                "plan_name": {
                    "value": "unitedhealthcare choice plus",
                    "scores": [
                        "0.9953",
                        "0.9835"
                    ]
                },
                "plan_id": {
                    "value": "(80840) 911-80708-01",
                    "scores": [
                        "0.9942",
                        "0.9939"
                    ]
                }
            }
        }
    ],
    "response_metadata": {
        "limit": 4,
        "next_cursor": "IieuzkckWq0"
    }
}
```

{% endtab %}

{% tab title="400 Invalid parameters" %}

```javascript
{
    "message": "limit must be a positve integer and less than 500",
    "type": "Bad Request",
    "code": 400
}
```

{% endtab %}

{% tab title="401 Missing or invalid token" %}

```javascript
{
    "message": "Unknown authorization error - please check your token format and try again",
    "type": "Unauthorized",
    "code": 401
}
```

{% endtab %}

{% tab title="403 Token is expired " %}

```javascript
{
    "message": "Token is expired",
    "type": "Authentication Timeout",
    "code": 419
}
```

{% endtab %}
{% endtabs %}

The `next_cursor` field is only present in the `response_metadata` when there are additional results to request.

The `completed` card in this example is truncated, for a full card and supported states, please see [Get Card](#get-card) below.

{% tabs %}
{% tab title="Curl" %}

```bash
curl --location --request GET 'https://sandbox.cardscan.ai/v1/cards' \
--header 'Authorization: Bearer endusertokenXXX' 
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const client = new CardScanApi({
    sessionToken:token, 
    live: false
});

client.listCards()
.then((cards) => {
    //update UI.
})
.catch((error) => {
    //retry or update UI
});
```

{% endtab %}

{% tab title="Swift" %}

```swift
let apiClient = CardScanAPIClient(userToken: userToken, live: false)

apiClient.listCards(limit: 10) { result in
    switch result {
    case .failure(let error):
        print("listCards error \(error)")
    case .success(let cards):
        //update UI
    }
}
```

{% endtab %}
{% endtabs %}

### Search Cards

<mark style="color:blue;">`GET`</mark> `https://sandbox.cardscan.ai/v1/cards/search`

Search through your card records using text queries to find specific cards by member name, payer, plan details, or other extracted information.

#### Query Parameters

| Name   | Type    | Description                                                                                               |
| ------ | ------- | --------------------------------------------------------------------------------------------------------- |
| query  | string  | **Required.** Search query to match against card data (member names, payer names, plan information, etc.) |
| cursor | string  | Used to paginate through results when count is greater than limit.                                        |
| limit  | integer | <p>Count of cards to return.</p><p><strong>Default</strong>: 50</p><p><strong>Max:</strong> 500</p>       |

{% tabs %}
{% tab title="200 Successful Response" %}

```javascript
{
    "cards": [
        {
            "card_id": "1bab2f3c-cfbe-4f22-b480-b389ece57f7e",
            "state": "completed",
            "created_at": "2021-07-30 19:56:40.638894+00:00",
            "details": {
                "member_name": {
                    "value": "john doe",
                    "scores": ["0.9974", "0.8879"]
                },
                "payer_name": {
                    "value": "unitedhealthcare",
                    "scores": ["0.9953", "0.9835"]
                }
            }
        }
    ],
    "response_metadata": {
        "limit": 50,
        "next_cursor": "IieuzkckWq0"
    }
}
```

{% endtab %}

{% tab title="400 Invalid parameters" %}

```javascript
{
    "message": "query parameter is required",
    "type": "Bad Request",
    "code": 400
}
```

{% endtab %}

{% tab title="401 Missing or invalid token" %}

```javascript
{
    "message": "Unknown authorization error - please check your token format and try again",
    "type": "Unauthorized",
    "code": 401
}
```

{% endtab %}

{% tab title="403 Token is expired" %}

```javascript
{
    "message": "Token is expired",
    "type": "Authentication Timeout",
    "code": 419
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --location --request GET 'https://sandbox.cardscan.ai/v1/cards/search?query=john%20doe&limit=10' \
--header 'Authorization: Bearer endusertokenXXX' 
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const client = new CardScanApi({
    sessionToken:token, 
    live: false
});

client.searchCards("john doe", {limit: 10})
.then((cards) => {
    //update UI.
})
.catch((error) => {
    //retry or update UI
});
```

{% endtab %}

{% tab title="Swift" %}

```swift
let apiClient = CardScanAPIClient(userToken: userToken, live: false)

apiClient.searchCards(query: "john doe", limit: 10) { result in
    switch result {
    case .failure(let error):
        print("searchCards error \(error)")
    case .success(let cards):
        //update UI
    }
}
```

{% endtab %}
{% endtabs %}

### Get Card

<mark style="color:blue;">`GET`</mark> `https://sandbox.cardscan.ai/v1/cards/:cardId`

#### Path Parameters

| Name                                     | Type   | Description  |
| ---------------------------------------- | ------ | ------------ |
| cardId<mark style="color:red;">\*</mark> | string | UUID of card |

{% tabs %}
{% tab title="200 Successful response" %}

```javascript
{
    "card_id": "c1b93738-ddc0-4beb-9936-1f93fe0e4279",
    "state": "completed",
    "created_at": "2025-04-24 13:58:30.820353+00:00",
    "details": {
        "group_number": {
            "value": "98755",
            "scores": ["0.995", "0.999"]
        },
        "member_number": {
            "value": "128845682",
            "scores": ["0.995", "0.999"]
        },
        "member_name": {
            "value": "emily dickinson",
            "scores": ["0.994", "0.998"]
        },
        "dependent_names": [
            {
                "value": "richard dickinson",
                "scores": ["0.995", "0.999"]
            }
        ],
        "payer_name": {
            "value": "unitedhealthcare",
            "scores": ["0.737", "0.999"]
        },
        "payer_id": {
            "value": "87726",
            "scores": ["0.995", "0.999"]
        },
        "plan_name": {
            "value": "unitedhealthcare choice plus",
            "scores": ["0.967", "0.992"]
        },
        "rx_bin": {
            "value": "610279",
            "scores": ["0.995", "0.999"]
        },
        "rx_pcn": {
            "value": "9987",
            "scores": ["0.991", "0.999"]
        },
        "rx_issuer": {
            "value": "(80840) 911-80708-01",
            "scores": ["0.994", "0.999"]
        },
        "pharmacy_benefit_manager": {
            "value": "optumrx",
            "scores": ["0.601", "0.999"]
        }
    },
    "payer_match": {
        "cardscan_payer_id": "pay_8otorlr4",
        "cardscan_payer_name": "UNITEDHEALTHCARE",
        "score": "0.952",
        "matches": [
            {
                "clearinghouse": "Availity",
                "payer_id": "87726",
                "transaction_type": "professional",
                "payer_name": "UNITEDHEALTHCARE",
                "cardscan_payer_id": "pay_8otorlr4",
                "score": "0.952",
                "metadata": {
                    "last_updated": "2025-04-07T01:39:42.292212+00:00",
                    "source": "2025-04-06v1.0"
                }
            },
            {
                "clearinghouse": "Availity", 
                "payer_id": "87726",
                "transaction_type": "professional",
                "payer_name": "UNITEDHEALTHCARE DEFINITY HEALTH PLAN",
                "cardscan_payer_id": "pay_6lsgc6ns",
                "score": "0.9",
                "metadata": {
                    "last_updated": "2025-04-07T01:39:42.292312+00:00",
                    "source": "2025-04-06v1.0"
                }
            }
        ],
        "change_healthcare": [],
        "custom": [
            {
                "custom_payer_id": "UHC",
                "custom_payer_name": "United Healthcare",
                "custom_payer_name_alt": "United Healthcare Legacy",
                "score": "1.0",
                "source": "custom_payer_list_20240212"
            },
            {
                "custom_payer_id": "UHC",
                "custom_payer_name": "United Healthcare Oxford",
                "custom_payer_name_alt": "United Healthcare Legacy", 
                "score": "1.0",
                "source": "custom_payer_list_20240212"
            }
        ]
    },
    "metadata": {
        "insurance_scan_version": "malbec-1.0",
        "payer_match_version": "hybrid-1.2"
    },
    "images": {
        "front": {
            "url": "https://cardscan-sandbox-uploads-us-east-1.s3-accelerate.amazonaws.com/..."
        }
    },
    "deleted": false
}
```

{% endtab %}

{% tab title="400 Invalid UUID" %}

```javascript
{
    "message": "Invalid card_id, the ID must be formatted as a UUID.",
    "type": "Bad Request",
    "code": 400
}
```

{% endtab %}

{% tab title="401 Missing or invalid token" %}

```javascript
{
    "message": "Unknown authorization error - please check your token format and try again",
    "type": "Unauthorized",
    "code": 401
}
```

{% endtab %}

{% tab title="403 Token is expired" %}

```javascript
{
    "message": "Token is expired",
    "type": "Authentication Timeout",
    "code": 419
}
```

{% endtab %}

{% tab title="404 Card not found" %}

```javascript
{
    "message": "No resource found for card_id - a1d743ee-3bb9-468d-a2c5-4e33fa0e1c6a",
    "type": "Not Found",
    "code": 404
}
```

{% endtab %}
{% endtabs %}

Cards returned by this endpoint and the `/v1/cards` endpoint have a state field:

| Value          | Description                                                                       |
| -------------- | --------------------------------------------------------------------------------- |
| **pending**    | This card ID has been reserved but a corresponding file has not yet been uploaded |
| **processing** | The card is being processed by our ML pipeline.                                   |
| **completed**  | Card processing is completed and the card `details` are available.                |
| **error**      | An error has occurred, see `error_message` for more details.                      |
| **unknown**    | An unknown issue has occurred, please contact support for help.                   |

![](https://423317997-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MYkGp0C8rvjnJYLAI_u%2F-MgCWKAL5a4fxIzFaXR7%2F-MgCf64OkCcHuY6VvkIn%2Fimage.png?alt=media\&token=3a631637-25a3-4cb6-97e9-25dddcd77996)

After being processed by the ML pipeline, each element is labeled and when the probability is above our minimum threshold the results are returned.

| Name                                                                                                                       | Description                                                                                                                      | Example                                                                            |
| -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **group\_number**                                                                                                          | The group number identifies the specific benefits associated with the plan. This is missing with some payers and exchange plans. | *98755*                                                                            |
| **member\_number**                                                                                                         | A unique identifier for each member and dependent. This is used to verify coverage and arrange payment for services.             | *128845682*                                                                        |
| **payer\_name**                                                                                                            | The name of the health insurance payer or 3rd party administrator.                                                               | *unitedhealthcare*                                                                 |
| **payer\_id**                                                                                                              | The payer ID or EDI for the insurance company. This is as written on the card and not matched to a clearing house.               | *87726*                                                                            |
| <p><strong>rx\_bin</strong></p><p><strong>rx\_pcn</strong></p><p><strong>rx\_group</strong><br><strong>rx\_id</strong></p> | These are used to identify how a prescription drug will be reimbursed and where a pharmacy can send a reimbursement claim to     | <p><em>610279</em></p><p><em>9987</em></p><p><em>UHC</em><br><em>12458765</em></p> |
| **member\_name**                                                                                                           | Most often the policyholder, but on some cards this is the dependent the card was issues to.                                     | *Emily Dickinson*                                                                  |
| **dependent\_names**                                                                                                       | This is a list of all dependents found on the card.                                                                              | *Richard Dickinson*                                                                |
| **plan\_name**                                                                                                             | Our best attempt to determine the name of the plan for this card. This is missing on many cards.                                 | *unitedhealthcare choice plus*                                                     |
| **plan\_id**                                                                                                               | An identifier representing the plan associated with this card.                                                                   | *(80840) 911-80708-01*                                                             |
| **rx\_issuer**                                                                                                             | An identifier representing the prescription plan associated with this card.                                                      | *(80840) 911-80708-01*                                                             |
| **pharmacy\_benefit\_manager**                                                                                             | The pharmacy benefit manager (PBM) that processes prescription claims for this plan.                                             | *optumrx*                                                                          |
| **card\_specific\_id**                                                                                                     | A non-specific but prominent identifier found on the card.                                                                       | *54243*                                                                            |
| **client\_name**                                                                                                           | The name of the employer who is contracted with the 3rd party administrator.                                                     | *Apple, Inc.*                                                                      |
| **plan\_details**                                                                                                          | When available a list of: deductibles, co-pays, co-insurance, PCP name.                                                          | <p><em>Office: $25</em></p><p><em>ER: $300</em></p>                                |
| **start\_date**                                                                                                            | The date when coverage starts.                                                                                                   | *04/01/2021*                                                                       |
| **phone\_numbers**                                                                                                         | A list of all phone numbers found of the front and back of the card.                                                             | 800-400-5251                                                                       |
| **addresses**                                                                                                              | A list of all addresses found on the card.                                                                                       | <p>UnitedHealthcare</p><p>P.O. Box 740800</p><p>Atlanta, GA 30374-0800</p>         |

### Response Fields Outside of Details

| Name             | Description                                                                                                  | Example                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| **payer\_match** | Comprehensive payer matching results including clearinghouse matches, custom matches, and confidence scores. | *See* [*Payer Matching*](https://docs.cardscan.ai/advanced-features/payer-matching) *for details* |
| **metadata**     | API version information including the insurance scan model version and payer match version used.             | *{"insurance\_scan\_version": "malbec-1.0", "payer\_match\_version": "hybrid-1.2"}*               |
| **images**       | Signed URLs for accessing the uploaded card images. URLs are valid for 24 hours.                             | *{"front": {"url": "https\://..."}}*                                                              |
| **deleted**      | Boolean indicating whether this card has been marked as deleted.                                             | *false*                                                                                           |

{% hint style="info" %}
**Note:** If an element is missing from the `details` object, it means it is either not available on this type of card, or we did not have a high enough confidence to return it.
{% endhint %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --request GET 'https://sandbox.cardscan.ai/v1/cards/a1d743ee-3bb9-468d-a2c5-4e33fa0e1c6e' \
--header 'Authorization: Bearer endusertokenXXX'
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const client = new CardScanApi({
    sessionToken:token, 
    live: false
});

client.getCard(cardId)
.then((card) => {
    //update UI.
})
.catch((error) => {
    //retry or update UI
});
```

{% endtab %}

{% tab title="Swift" %}

```swift
let apiClient = CardScanAPIClient(userToken: userToken, live: false)

apiClient.getCard(cardUUID: cardId) { result in
    switch result {
    case .failure(let error):
        print("getCard error \(error)")
    case .success(let card):
        //update UI
    }
}
```

{% endtab %}
{% endtabs %}

### Delete Card

<mark style="color:red;">`DELETE`</mark> `https://sandbox.cardscan.ai/v1/cards/:cardId`

This will trigger a soft delete of the specified card.

#### Path Parameters

| Name                                     | Type   | Description      |
| ---------------------------------------- | ------ | ---------------- |
| cardId<mark style="color:red;">\*</mark> | String | UUID of the card |

{% tabs %}
{% tab title="204" %}

{% endtab %}

{% tab title="404" %}

{% endtab %}

{% tab title="403" %}

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Note**: All of the images, ML results, eligibility results, and PHI will be removed, but the card record and performance statistics will remain.
{% endhint %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --request DELETE 'https://sandbox.cardscan.ai/v1/cards/a1d743ee-3bb9-468d-a2c5-4e33fa0e1c6e' \
--header 'Authorization: Bearer endusertokenXXX'
```

{% endtab %}
{% endtabs %}

### Flag Card <a href="#flag-card" id="flag-card"></a>

<mark style="color:green;">`POST`</mark> `https://sandbox.cardscan.ai/v1/cards/:cardId/flag`

This endpoint allows you to flag a specific card with a particular type of flag. Flags are used to mark cards for special attention or action.

**Path Parameters**

| Name                                     | Type   | Description      |
| ---------------------------------------- | ------ | ---------------- |
| cardId<mark style="color:red;">\*</mark> | String | UUID of the card |

#### Request Body

<table><thead><tr><th width="149">Name</th><th width="111">Type</th><th width="232">Allowed values</th><th>Description</th></tr></thead><tbody><tr><td>flag_type<mark style="color:red;">*</mark></td><td>String</td><td><ul><li>missing_elements</li><li>incorrect_elements</li><li>bad_payer_match</li><li>unreadable_text</li><li>eligibility_issue</li><li>other</li></ul></td><td>The flag type used to mark the card</td></tr><tr><td>message</td><td>String</td><td></td><td>An optional message to add additional information</td></tr></tbody></table>

{% tabs %}
{% tab title="200 Successful response" %}

```json
{
    "message": "Card flagged successfully"
}
```

{% endtab %}

{% tab title="400 Flag type required" %}

```json
{
    "message": "flag_type is required",
    "type": "Bad Request",
    "code": 400
}
```

{% endtab %}

{% tab title="400 Invalid flag type" %}

```json
{
    "message": "Invalid flag_type",
    "type": "Bad Request",
    "code": 400
}
```

{% endtab %}
{% endtabs %}

## Magic Links

### Generate magic link

<mark style="color:green;">`GET`</mark> `/generate-magic-link`

Generates a magic link for the currently authenticated user. The generated token expires in one hour. This endpoint is called by the React Widget when using the [Web To Mobile Handoff](https://docs.cardscan.ai/advanced-features/web-to-mobile-handoff) feature.

{% tabs %}
{% tab title="200" %}

```json
{
    "magic_link": "https://sandbox.cardscan.ai/v1/validate-magic-link?token=<token>",
    "token": "<token>",
    "expires_at": "2024-06-27T03:48:01.049866"
}
```

{% endtab %}

{% tab title="403" %}

```json
{
    "message": "User is not authorized for this resource",
    "type": "Access Denied",
    "code": 403
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --request GET 'https://sandbox.cardscan.ai/v1/generate-magic-link \
--header 'Authorization: Bearer endusertokenXXX'
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const client = new CardScanApi({
    sessionToken:token, 
    live: false
});

client.generateMagicLink()
.then((response) => {
    // ...
})
.catch((error) => {
    // ...
});
```

{% endtab %}
{% endtabs %}

### Validate magic link

<mark style="color:green;">`GET`</mark> `/validate-magic-link?token=<magic-token>`

Validates that the provided magic link token is valid and if so, returns an [Access Token](#get-access-token) with limited capabilities. You need to use this endpoint if you want to self-host the [Web To Mobile Handoff](https://docs.cardscan.ai/advanced-features/web-to-mobile-handoff) feature.

{% tabs %}
{% tab title="200" %}

```json
{
  "IdentityId": "us-east-1:0236cb77-ac53-460d-ba39-60b186af2897",
  "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
```

{% endtab %}

{% tab title="400: Invalid token" %}

```json
{
"message": "Invalid token",
"type": "Bad Request",
"code": 400
}
```

{% endtab %}

{% tab title="410: Expired token" %}

```json
{
"message": "Token expired - <token>",
"type": "Expired",
"code": 410
}
```

{% endtab %}

{% tab title="404" %}

```json
{
"message": "No resource found for token - badtokenbadtok",
"type": "Not Found",
"code": 404
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --request GET 'https://sandbox.cardscan.ai/v1/validate-magic-link?token=<token> \
--header 'Authorization: Bearer endusertokenXXX'
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
const token = "your-magic-token";

fetch(`${baseURL}/validate-magic-link?token=${token}`)
.then((res) => res.json())
.then((data) => {
  setToken(data.Token); // Access token
})
.catch((err) => console.log(err));

```

{% endtab %}
{% endtabs %}

## Eligibility Verification

Our Eligibility Verification Endpoints offer a seamless way to check the insurance eligibility of patients. They provide real-time verification of coverage details, ensuring accurate and efficient processing of healthcare services.

Please see the [#eligibility-verification](#eligibility-verification "mention") page for full details on the product offering.

Our Eligibility Verification Endpoints operate similarly to our Insurance Card Scanning Endpoints. Users can create a new eligibility request, which is processed asynchronously. The system updates the record as the state changes, providing real-time insights into insurance coverage and benefits.

{% hint style="info" %}
**Note:** Currently a completed insurance card scan is required to start the eligibility verification process.
{% endhint %}

{% openapi src="<https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2F9obKv2uBd5nth7mRMHNH%2Fcardscan%20(1).yml?alt=media&token=95d8f3f6-37cc-496e-a30c-c29b797af735>" path="/eligibility" method="post" %}
[cardscan (1).yml](https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2F9obKv2uBd5nth7mRMHNH%2Fcardscan%20\(1\).yml?alt=media\&token=95d8f3f6-37cc-496e-a30c-c29b797af735)
{% endopenapi %}

To create an eligibility request, users must provide subscriber and dependent demographics along with provider details, including a National Provider Identifier (NPI). This information is essential for accurately verifying insurance eligibility.

You can locate a providers NPI on the [NPPES NPI Registry](https://npiregistry.cms.hhs.gov/search%23pageStart) search page.

{% openapi src="<https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2F9obKv2uBd5nth7mRMHNH%2Fcardscan%20(1).yml?alt=media&token=95d8f3f6-37cc-496e-a30c-c29b797af735>" path="/eligibility/{eligibility\_id}" method="get" %}
[cardscan (1).yml](https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2F9obKv2uBd5nth7mRMHNH%2Fcardscan%20\(1\).yml?alt=media\&token=95d8f3f6-37cc-496e-a30c-c29b797af735)
{% endopenapi %}

{% openapi src="<https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2F9obKv2uBd5nth7mRMHNH%2Fcardscan%20(1).yml?alt=media&token=95d8f3f6-37cc-496e-a30c-c29b797af735>" path="/eligibility" method="get" %}
[cardscan (1).yml](https://423317997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MYkGp0C8rvjnJYLAI_u%2Fuploads%2F9obKv2uBd5nth7mRMHNH%2Fcardscan%20\(1\).yml?alt=media\&token=95d8f3f6-37cc-496e-a30c-c29b797af735)
{% endopenapi %}

## Health Check Endpoints

### Public Health Check

<mark style="color:blue;">`GET`</mark> `https://sandbox.cardscan.ai/v1/ping`

A public health check endpoint that returns the service status and feature flags. No authentication required.

{% tabs %}
{% tab title="200 Successful Response" %}

```json
{
    "timestamp": "2024-02-05T15:50:14.856792Z",
    "feature_flags": {
        "enable_advanced_ocr": true,
        "enable_payer_matching": true
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --request GET 'https://sandbox.cardscan.ai/v1/ping'
```

{% endtab %}
{% endtabs %}

### Authenticated Health Check

<mark style="color:blue;">`GET`</mark> `https://sandbox.cardscan.ai/v1/authping`

An authenticated health check endpoint that verifies your API key or session token is valid and returns service status.

{% tabs %}
{% tab title="200 Successful Response" %}

```json
{
    "timestamp": "2024-02-05T15:50:14.856792Z",
    "authenticated": true,
    "account_id": "D05BD263-CC9E-437D-9AEE-9846196F18BA"
}
```

{% endtab %}

{% tab title="401 Missing or invalid token" %}

```json
{
    "message": "Unknown authorization error - please check your token format and try again",
    "type": "Unauthorized",
    "code": 401
}
```

{% endtab %}

{% tab title="403 Token is expired" %}

```json
{
    "message": "Token is expired",
    "type": "Authentication Timeout",
    "code": 419
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Curl" %}

```bash
curl --request GET 'https://sandbox.cardscan.ai/v1/authping' \
--header 'Authorization: Bearer sk_test_cardscan_ai_XXXXXXXXXXXXXXX'
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cardscan.ai/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.