> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cove.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Welcome to the Cove API Quickstart! This guide provides a detailed walkthrough of how to use the API, from setting up your account to conducting applicant screenings.

# Cove API Screening Quickstart

## Introduction

The Cove API enables easy screening of users. This guide provides a detailed walkthrough of how to use the API, from setting up your account to conducting applicant screenings.

## Base URL

```md theme={null}
https://sandbox-api.cove.dev
```

## Detailed Workflow

### Step 1: Request Login Credentials

To begin using the Cove API, you need login credentials. Send an email to [team@cove.dev](mailto:team@cove.dev) requesting access to your account and the dashboard.
Once you receive your credentials, you can authenticate and start making API calls.

***

### Step 2: Authenticate

Before accessing other endpoints, you must authenticate using the `/v1/auth/login` endpoint to obtain an access token.

#### Endpoint

```md theme={null}
POST /v1/auth/login
```

#### Description

This endpoint validates your username and password. If successful, it returns an `accessToken` that you must include in all subsequent API calls.

#### Request Headers

* `Content-Type`: `application/json`
* `Accept`: `application/json`

#### Request Body

```json theme={null}
{
  "username": "<string>",
  "password": "<string>"
}
```

#### Example

```sh theme={null}
curl -X POST https://sandbox-api.cove.dev/v1/auth/login \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "username": "your-username",
  "password": "your-password"
}'
```

* **Success (200)**:

  ```json theme={null}
  {
    "accessToken": "<string>"
  }
  ```

* **Error (401)**: Unauthorized.

#### Usage of Token

Include the `accessToken` in the `Authorization` header for all subsequent requests:

```md theme={null}
Authorization: <accessToken>
```

***

### Step 3: Setup a Flow

Before you can create a screening, you need to setup a flow. You can do this in the dashboard ([https://sandbox.cove.dev/](https://sandbox.cove.dev/)).
Remember: Flows allow you to create custom screening processes tailored to your specific needs. Instead of using predefined checks,
you can define a sequence of steps and reuse them across multiple screenings. Once you have created a flow, note the `flowID`.
You will use it in the next step.

***

### Step 4: Send Screening Link

You can initiate a screening process by sending a link to the applicant. Use the `/v2/screening/send` endpoint for this.

#### Endpoint

```
POST /v2/screening/send
```

#### Description

Generates and sends a screening link to the applicant, enabling them to complete the screening process.

#### Headers

* `Authorization`: `<API Key>`
* `Content-Type`: `application/json`
* `Accept`: `application/json`

#### Request Body

```json theme={null}
{
  "flowId": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "firstName": "<string>",
  "lastName": "<string>",
  "metadata": {
    "customKey": "<any>"
  },
  "options": {
    "emailDisabled": "<boolean>",
    "smsDisabled": "<boolean>"
  },
  "payer": "PAYER_SELF"
}
```

#### Example

```sh theme={null}
curl -X POST https://sandbox-api.cove.dev/v2/screening/send \
-H "Authorization: your-access-token" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "flowId": "flow-id-from-previous-step",
  "email": "applicant@example.com",
  "phone": "+14160001111",
  "firstName": "John",
  "lastName": "Doe",
  "metadata": {
    "customKey": "customValue"
  },
  "options": {
    "emailDisabled": false,
    "smsDisabled": false
  },
  "payer": "PAYER_SELF"
}'
```

* **Success (200)**:

  ```json theme={null}
  {
    "message": "<string>",
    "userId": "<string>",
    "screeningId": "<string>",
    "screeningLink": "<string>"
  }
  ```

#### Notes

* Provide accurate applicant information to ensure the screening link reaches the right individual.
* The `screeningId` from this response will be required for retrieving the screening results or for other requests related to the screening.
* If you set `emailDisabled` to `true`, the applicant will not receive an email.
  If you set `smsDisabled` to `true`, the applicant will not receive an SMS. You will be responsible for sharing the `screeningLink` with the applicant.

***

### Step 5: Generate an iFrame for the Screening (Optional)

If you prefer to embed the screening process directly into your application, you can generate an iFrame for the screening link.
Use the `screeningLink` obtained from the previous step to create an iFrame. It will go in the `src` attribute of the iFrame.

#### Example

```html theme={null}
<iframe 
  title="Cove Embed"
  id="cove-embed"
  allow="camera; microphone; accelerometer"
  sandbox="allow-scripts allow-same-origin allow-forms"
  height="800"
  width="100%"
  src="{url}" 
></iframe>

<script>
  // For security, verify the origin
  if (
    event.origin !== 'https://app.cove.dev' &&
    event.origin !== 'https://sandbox.cove.dev' &&
    event.origin !== 'http://localhost:3000' &&
    event.origin !== 'http://localhost:3001'
  ) {
    return;
  }

  window.addEventListener('message', function(event) {
    const coveEmbed = document.getElementById('cove-embed');
    coveEmbed?.contentWindow?.postMessage(event.data, "*");

    // For security, verify the origin
    if (
      event.origin !== 'https://app.cove.dev' &&
      event.origin !== 'https://sandbox.cove.dev' &&
      event.origin !== 'http://localhost:3000'
    ) {
      return;
    }

    if (
      event.data.source === "cove-embed" &&
      event.data.status === "USER_COMPLETE"
    ) {
      console.log("message:", event.data);
      coveEmbed.remove();
    }
  });
</script>
```

***

### Step 6: Get Screening Results

There are two ways to get screening results. You can either retrieve the raw screening data or you can retrieve a PDF report of the screening.
You can also do both. The raw data is useful for programmatic access, while the PDF report is useful for sharing with stakeholders or for record-keeping.

* [Step 6.1: Retrieve Screening Data](#step-61-retrieve-screening-data)
* [Step 6.2: Retrieve Screening Report PDF](#step-62-retrieve-screening-report-pdf)

***

<a id="step-61-retrieve-screening-data" />

### Step 6.1: Retrieve Screening Data

Once the applicant completes the screening, you can fetch their results using the `/v2/screening/:screeningId` endpoint.

#### Endpoint

```
GET /v2/screening/:screeningId
```

#### Description

Retrieves detailed screening results for a specific session.

#### Headers

* `Authorization`: `<API Key>`
* `Accept`: `application/json`

#### URL Parameters

* `screeningId`: (Required) Unique identifier for the session.

#### Example

```sh theme={null}
curl -X GET https://sandbox-api.cove.dev/v2/screening/<screeningId> \
-H "Authorization: your-access-token" \
-H "Accept: application/json"
```

* **Success (200)**:

  ```json theme={null}
  {
    "user": "<string>",
    "flowId": "<string>",
    "metadata": { ... },
    "screeningSteps": { ... },
    "data": { ... }
  }
  ```

#### Notes

* Use this endpoint to evaluate the applicant’s suitability based on their screening data.

***

<a id="step-62-retrieve-screening-report-pdf" />

### Step 6.2: Retrieve Screening Report PDF

Once the applicant completes the screening, you can also fetch their results as a PDF
report using the `/v2/screening/:screeningId/report` endpoint.

#### Endpoint

```
GET /v2/screening/:screeningId/report
```

#### Description

Retrieves detailed screening results for a specific session as a PDF report.

#### Headers

* `Authorization`: `<API Key>`
* `Accept`: `application/json`

#### URL Parameters

* `screeningId`: (Required) Unique identifier for the session.

#### Example

```sh theme={null}
curl -X GET https://sandbox-api.cove.dev/v2/screening/<screeningId>/report \
-H "Authorization: your-access-token" \
-H "Accept: application/json"
```

* **Success (200)**:

  ```json theme={null}
  {
    "url": "<string>"
  }
  ```

#### Notes

* Use this endpoint to evaluate the applicant’s suitability based on their screening data.

***

### Step 7: Run Manual Credit Check (If Applicable)

If an applicant's credit check was not successful after they've completed the screening application, or if you are using your own
consent form and application and are not using other nodes in the flow, you can run a credit check for the applicant yourself.

* [Step 7.1: Add Data for Credit Check](#step-71-add-data-for-credit-check)
* [Step 7.2: Run the Credit Check](#step-72-run-the-credit-check)

<a id="step-71-add-data-for-credit-check" />

### Step 7.1: Add Data for Credit Check

Before running a credit check, you must add the applicant’s data to their account.

```
POST /v1/user/:userId
```

#### Description

Update user's information for the screening.

#### Headers

* `Authorization`: `<API Key>`
* `Content-Type`: `application/json`
* `Accept`: `application/json`

#### Request Body

```json theme={null}
{
  "firstName": "<string>",
  "lastName": "<string>",
  "address": {
    "street": "<string>",
    "city": "<string>",
    "provinceState": "<string>",
    "country": "<string>",
    "postalCode": "<string>"
  },
  "sin": "<string>",
  "dateOfBirth": "<string>"
}
```

#### Example

```sh theme={null}
curl -X POST https://sandbox-api.cove.dev/v1/user/<userId> \
-H "Authorization: your-access-token" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "firstName": "John",
  "lastName": "Doe",
  "address": {
    "street": "123 Main St",
    "city": "Toronto",
    "provinceState": "ON",
    "country": "Canada",
    "postalCode": "M5H 2N2"
  },
  "sin": "123-456-789",
  "dateOfBirth": "1990-01-01"
}'
```

* **Success (200)**:

  ```json theme={null}
  {
    "message": "<string>",
    "userId": "<string>"
  }
  ```

#### Notes

* Ensure that the `userId` corresponds to the applicant you are screening.

<a id="step-72-run-the-credit-check" />

### Step 7.2: Run the Credit Check

Once the applicant’s data is added, run the credit check.

```
POST /v2/screening/run
```

#### Description

Run the screening for the applicant using the provided user data.

#### Headers

* `Authorization`: `<API Key>`
* `Content-Type`: `application/json`
* `Accept`: `application/json`

#### Request Body

```json theme={null}
{
  "screeningId": "<string>"
}
```

#### Example

```sh theme={null}
curl -X POST https://sandbox-api.cove.dev/v2/screening/run \
-H "Authorization: your-access-token" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "screeningId": "screening-id-from-earlier-step"
}'
```

* **Success (200)**:

  ```json theme={null}
  {
    "message": "<string>",
    "userId": "<string>",
    "screeningId": "<string>"
  }
  ```

#### Notes

* You are responsible for ensuring compliance with consent laws when running a credit check yourself.

***

### Step 8: Re-send a Specific Screening Step (If Skipped)

If an applicant skipped a step (e.g., bank verification) or needs to re-complete a part of the screening,
you can re-send the screening link for that specific step using the `/v2/screening/resend-step` endpoint.

#### Endpoint

```
POST /v2/screening/resend-step
```

#### Description

Re-sends the screening link for a specific step in the flow to the applicant. This is helpful if a step
was skipped or needs to be redone (e.g., `FINANCIAL_VERIFICATION`).

#### Headers

* `Authorization`: `<API Key>`
* `Content-Type`: `application/json`
* `Accept`: `application/json`

#### Request Body

```json theme={null}
{
  "screeningId": "<string>",
  "skippedStepName": "<string>", 
  "options": {
    "emailDisabled": "<boolean>",
    "smsDisabled": "<boolean>"
  }
}
```

#### Example

```sh theme={null}
curl -X POST https://sandbox-api.cove.dev/v2/screening/resend-step \
-H "Authorization: Bearer your-access-token" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
  "screeningId": "your-screening-id",
  "skippedStepName": "FINANCIAL_VERIFICATION",
  "options": {
    "emailDisabled": true,
    "smsDisabled": true
  }
}'
```

* **Success (200)**:

  ```json theme={null}
  {
    "message": "Flow screening sent successfully",
    "user_id": "6830d7964f5de74a4e600869",
    "retry_link": "https://sandbox.cove.dev/s/6830d7964f5de74a4e60086b?resent=FINANCIAL_VERIFICATION&login-code=abc123&email=user%40example.com"
  }
  ```

#### Notes

* The `retry_link` can be used to direct the applicant to the specific step that was skipped.
* Valid values for `skippedStepName` include `FINANCIAL_VERIFICATION`, `ID_VERIFICATION`, `EMPLOYMENT`, `CREDIT_CHECK`, `RESIDENCE_HISTORY`,
  `CUSTOM_FORM`, and `PERSONAL_INFO` with more being added in the future.
* This feature is particularly useful when an applicant abandons the process or encounters an issue with a specific step.

***

## Additional Information

* All endpoints require HTTPS communication.
* Errors are returned in JSON format with appropriate HTTP status codes.
* For detailed documentation, visit the [Cove API Docs](https://docs.cove.dev).

***

## Need Help?

For further assistance, contact [team@cove.dev](mailto:team@cove.dev).