# 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 %}