### Sandbox Environment Details

Source: https://docs.dots.dev/overview/environments

Detailed information about the Sandbox environment, including its purpose, features, setup process, and specific payout method behaviors.

```APIDOC
## Sandbox Environment

The Sandbox environment simulates the live production environment, enabling you to develop and test your integration safely. Use the Sandbox to build and verify your integration before upgrading to the Production environment.

The Sandbox environment provides the following features:

* Mirrors all production features with minor differences to facilitate testing.
* Allows you to use duplicate phone numbers, unlike the production environment.
* Each new account is pre-funded with $100, and additional funds can be added as needed.

### Sandbox Setup

To use the Sandbox environment, you should follow the steps presented below:

1. Log in to the Dots Dashboard and toggle the **View Sandbox Environment** in the upper left corner. A **SANDBOX MODE** badge appears on the top of the page.
2. Set up an application and generate API keys.
3. Use `https://pls.senddotssandbox.com/api` for Sandbox API requests.

### Sandbox Payouts

When using the Sandbox environment, some of the payout methods present specific behavior. Consider the following characteristics when executing a payout with the following methods:

| Method     | Description                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| **ACH**    | Connect live bank accounts via Plaid. Transactions won't go through, but the integration should be verified. |
| **PayPal** | Any email can be connected, and all transactions will return a successful response.                          |
| **Venmo**  | Any phone number can be connected, and all transactions will return a successful response.                   |
```

--------------------------------

### Flow Creation Response Example (JSON)

Source: https://docs.dots.dev/guides/white-labeled-payouts

Example JSON response when creating a Flow for managing payout methods. It includes details like the flow ID, user ID, and a link to the Flow for user interaction.

```json
{
  "completed_steps": [],
  "created": "2024-07-30T13:19:09.438268",
  "id": "17f357c1-7f4d-4101-a2c0-8cb9c9947ac8",
  "link": "https://my-sandbox.dots.dev/flow/17f357c1-7f4d-4101-a2c0-8cb9c9947ac8",
  "metadata": null,
  "payout_link_id": null,
  "steps": [
    "manage-payouts"
  ],
  "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4"
}
```

--------------------------------

### Metadata Structure Example

Source: https://docs.dots.dev/references/metadata

This example illustrates a potential structure for the `metadata` object, showing various keys that could be used for tracking purposes like project IDs, order IDs, and product categories.

```APIDOC
## Metadata Object Structure

### Description
An example of how the `metadata` object can be structured with different key-value pairs for various use cases.

### Method
N/A (This is a data structure example, not an endpoint)

### Endpoint
N/A

### Parameters
#### Request Body
- **metadata** (object) - Required/Optional - A key-value object for custom data.
  - **vendor_id** (string) - Optional - Identifier for a vendor.
  - **order_id** (string) - Optional - Identifier for an order.
  - **product_category** (string) - Optional - Category of the product.
  - **sales_period** (string) - Optional - The sales period.

### Request Example
```json
{
  "metadata": {
    "vendor_id": "vendor_567",
    "order_id": "order_890",
    "product_category": "Electronics",
    "sales_period": "Q2 2024"
  }
}
```

### Response
#### Success Response (200)
- **metadata** (object) - The metadata object included in the request.
```

--------------------------------

### Create Fund Transfer Response (JSON)

Source: https://docs.dots.dev/guides/flow-payouts

Example response from the Dots API after creating a fund transfer. It includes the transfer amount, creation timestamp, unique ID, status (e.g., 'completed'), and associated transaction details.

```json
{
  "amount": "-1000",
  "created": "2024-07-11T21:17:33.959976",
  "external_data": {},
  "id": "847e70b4-e057-457e-aa89-ba0312f159c1",
  "metadata": null,
  "status": "completed",
  "status_history": [
    {
      "status": "completed",
      "timestamp": "Thu, 11 Jul 2024 21:17:33 GMT"
    }
  ],
  "transactions": [
    {
      "amount": "1000.0000000000",
      "created": "2024-07-11T21:17:33.950405",
      "destination_name": "enamored-education",
      "id": 767354,
      "metadata": null,
      "source_name": "TestWriteChoiceApp",
      "type": "balance"
    }
  ],
  "type": "balance",
  "user_id": "f33919ae-6793-41bd-b512-1ad3c19f4ecb"
}
```

--------------------------------

### Create Withdrawal Flow Response (JSON)

Source: https://docs.dots.dev/guides/flow-payouts

Example response from the Dots API after creating a withdrawal flow. It contains the flow ID, creation timestamp, the user ID associated with the flow, and a `link` that can be embedded in an iframe for the user to complete the payout process.

```json
{
  "completed_steps": [],
  "created": "2024-07-12T11:08:32.486385",
  "id": "6ad6b948-422d-4fc4-bd6c-fe1521639a2b",
  "link": "https://my-sandbox.dots.dev/flow/6ad6b948-422d-4fc4-bd6c-fe1521639a2b",
  "metadata": null,
  "payout_link_id": null,
  "steps": [
    "payout"
  ],
  "user_id": "f33919ae-6793-41bd-b512-1ad3c19f4ecb"
}
```

--------------------------------

### Create Withdrawal Flow (cURL)

Source: https://docs.dots.dev/guides/flow-payouts

Example of creating a withdrawal flow for a user using the Dots API. This endpoint is used to enable users to withdraw funds. It requires specifying 'payout' as a step. The response includes a unique link for the flow.

```sh
curl --request POST \
  --url https://pls.senddotssandbox.com/api/v2/flows/ \
  --header 'Authorization: Basic cGtfZGV2X0g3V0tFOXlTRGhqeW91dFZBNEk3RkxhVkUzaWg1OnNrX2Rldl9lekFPNXA0WUNJeld6RWgwam5ubHFrODRkQ3ZFOQ==' \
  --header 'Content-Type: application/json' \
  --data '{
    "steps": [
      "payout"
    ]
  }'
```

--------------------------------

### Create User with Metadata

Source: https://docs.dots.dev/references/metadata

This example demonstrates how to include metadata when creating a new user. The `metadata` object is used to store an `internal_id` for the user.

```APIDOC
## POST /api/v2/users

### Description
Creates a new user and allows for the inclusion of custom metadata.

### Method
POST

### Endpoint
/api/v2/users

### Parameters
#### Request Body
- **first_name** (string) - Required - The first name of the user.
- **last_name** (string) - Required - The last name of the user.
- **email** (string) - Required - The email address of the user.
- **country_code** (string) - Required - The country code for the user's phone number.
- **phone_number** (string) - Required - The phone number of the user.
- **metadata** (object) - Optional - A key-value object for custom data.
  - **internal_id** (string) - Example field within metadata.

### Request Example
```json
{
  "first_name": "Bob",
  "last_name": "Loblaw",
  "email": "bob@bobloblaw.com",
  "country_code": "1",
  "phone_number": "4154332334",
  "metadata": {
    "internal_id": "user_121344"
  }
}
```

### Response
#### Success Response (200)
- **user_id** (string) - The unique identifier for the created user.
- **first_name** (string) - The first name of the user.
- **last_name** (string) - The last name of the user.
- **email** (string) - The email address of the user.
- **metadata** (object) - The metadata object included in the request.
```

--------------------------------

### Create Flow for Default Payout Method (Shell)

Source: https://docs.dots.dev/guides/white-labeled-payouts

Creates a Flow to manage user payout methods. Requires a user ID and specifies 'manage-payouts' as the step. The response includes a link to embed or redirect the user to complete the setup.

```sh
curl --request POST \
  --url https://pls.senddotssandbox.com/api/v2/flows/ \
  --header 'Authorization: Basic cGtfZGV2X0g3V0tFOXlTRGhqeW91dFZBNEk3RkxhVkUzaWg1OnNrX2Rldl9lekFPNXA0WUNJeld6RWgwam5ubHFrODRkQ3ZFOQ==' \
  --header 'Content-Type: application/json' \
  --data '{
      "steps": [
        "manage-payouts"
      ],
      "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4"
    }'
```

--------------------------------

### Example Payout Link API Response (JSON)

Source: https://docs.dots.dev/guides/payout-links

This JSON object represents a typical response when creating a payout link via the Dots API. It includes details about the payout, such as amount, status, flow ID, and the shareable payout link.

```json
{
  "accounting_data": {
    "quickbooks_account_id": null
  },
  "amount": 123,
  "claimed_user_id": null,
  "created": "2024-07-11T12:31:33.479437",
  "delivery": {
    "country_code": null,
    "email": null,
    "method": "link",
    "phone_number": null
  },
  "description": null,
  "flow_id": "7c22fd05-147e-48bb-b008-f48f24b76ea4",
  "id": "e5d5863a-498d-4551-a3dc-e31012503f23",
  "link": "https://my-sandbox.dots.dev/flow/7c22fd05-147e-48bb-b008-f48f24b76ea4",
  "memo": null,
  "metadata": null,
  "payee": {
    "country_code": null,
    "email": null,
    "first_name": null,
    "last_name": null,
    "phone_number": null
  },
  "status": "delivered",
  "tax_exempt": false,
  "transfer_id": "c1d3ec40-e05e-4385-acd6-c587372c4c3a"
}
```

--------------------------------

### Create Fund Transfer (cURL)

Source: https://docs.dots.dev/guides/flow-payouts

Example of creating a fund transfer to a user account using the Dots API. This requires the target user's ID and the amount in cents. Negative amounts indicate transfers from the app to the user. The response shows the transfer details and status.

```sh
curl --request POST \
  --url https://pls.senddotssandbox.com/api/v2/transfers \
  --header 'Authorization:  Basic cGtfZGV2X0g3V0tFOXlTRGhqeW91dFZBNEk3RkxhVkUzaWg1OnNrX2Rldl9lekFPNXA0WUNJeld6RWgwam5ubHFrODRkQ3ZFOQ==' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": -1000,
    "user_id": "f33919ae-6793-41bd-b512-1ad3c19f4ecb"
  }'
```

--------------------------------

### Create Payout Request and Response (cURL, JSON)

Source: https://docs.dots.dev/guides/white-labeled-payouts

Demonstrates how to create a payout using the Dots API. The request includes user ID, amount, and platform details. The response shows the payout details, including its ID, status, and associated transaction information. This example requires a valid Authorization header.

```sh
curl --request POST \
  --url https://api.dots.dev/api/v2/payouts \
  --header 'Authorization: Basic cGtfZGV2X0g3V0tFOXlTRGhqeW91dFZBNEk3RkxhVkUzaWg1OnNrX2Rldl9lekFPNXA0WUNJeld6RWgwam5ubHFrODRkQ3ZFOQ==' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4", \
    "amount": 1000, \
    "platform": "default" \
    "fund`: "true" \
  }'
```

```json
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created": "2023-11-07T05:31:56Z",
  "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4",
  "status": "created",
  "type": "refill",
  "amount": 1000,
  "external_data": {
    "account_id": "<string>",
    "external_id": "<string>",
    "platform": "ach"
  },
  "transactions": [
    {
      "id": 123,
      "amount": 1000,
      "created": "2023-11-07T05:31:56Z",
      "source_name": "<string>",
      "destination_name": "<string>",
      "type": "balance",
      "metadata": "<string>"
    }
  ]
}
```

--------------------------------

### Create Payout with Idempotency Key (cURL)

Source: https://docs.dots.dev/references/idempotency

This example demonstrates how to create a payout request using cURL, including the mandatory 'idempotency_key' in the JSON body. This ensures that the payout operation is processed only once, even if the request is sent multiple times. The key should be a unique UUID generated by the client.

```sh
curl --request POST \
  --url https://api.dots.dev/api/v2/payouts \
  --header 'Authorization: Basic <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "amount": 123,
  "platform": "paypal",
  "account_id": "<string>",
  "fund": true,
  "tax_exempt": true,
  "idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": "<string>"
}'
```

--------------------------------

### Create Dots Onboarding Flow (cURL)

Source: https://docs.dots.dev/guides/flow-payouts

This snippet demonstrates how to create a new Dots onboarding Flow using the 'Create a Flow' endpoint. It requires App credentials for authentication and specifies the 'compliance' step for the onboarding process. The response provides a unique Flow ID and a link to embed the onboarding process.

```sh
curl --request POST \
  --url https://pls.senddotssandbox.com/api/v2/flows/ \
  --header 'Authorization: Basic cGtfZGV2X0g3V0tFOXlTRGhqeW91dFZBNEk3RkxhVkUzaWg1OnNrX2Rldl9lekFPNXA0WUNJeld6RWgwam5ubHFrODRkQ3ZFOQ==' \
  --header 'Content-Type: application/json' \
  --data '{ \
    "steps": [ \
      "compliance" \
    ], \
  }'
```

```json
{
  "completed_steps": [],
  "created": "2024-07-11T21:10:30.846081",
  "id": "b3293101-35ef-451a-aad4-881da3697c2f",
  "link": "https://my-sandbox.dots.dev/flow/b3293101-35ef-451a-aad4-881da3697c2f",
  "metadata": null,
  "payout_link_id": null,
  "steps": [
    "compliance"
  ],
  "user_id": null
}
```

--------------------------------

### Create a Flow

Source: https://docs.dots.dev/guides/flow-payouts

This endpoint creates a new Flow, which can be used for onboarding users. It allows specifying the steps to be included in the flow, such as 'compliance'. Authentication with App credentials is required.

```APIDOC
## POST /api/v2/flows/

### Description
Creates a new Flow for user onboarding, including specified steps like compliance.

### Method
POST

### Endpoint
https://pls.senddotssandbox.com/api/v2/flows/

### Parameters
#### Query Parameters
None

#### Request Body
- **steps** (array of strings) - Required - A list of steps to include in the flow, e.g., ["compliance"].

### Request Example
```json
{
  "steps": [
    "compliance"
  ]
}
```

### Response
#### Success Response (200)
- **completed_steps** (array) - Steps that have been completed.
- **created** (string) - Timestamp when the flow was created.
- **id** (string) - The unique identifier for the flow.
- **link** (string) - A URL to embed the onboarding process.
- **metadata** (object) - Additional metadata for the flow.
- **payout_link_id** (string) - The ID associated with a payout link.
- **steps** (array of strings) - The list of steps configured for the flow.
- **user_id** (string) - The unique identifier for the user, if available.

#### Response Example
```json
{
  "completed_steps": [],
  "created": "2024-07-11T21:10:30.846081",
  "id": "b3293101-35ef-451a-aad4-881da3697c2f",
  "link": "https://my-sandbox.dots.dev/flow/b3293101-35ef-451a-aad4-881da3697c2f",
  "metadata": null,
  "payout_link_id": null,
  "steps": [
    "compliance"
  ],
  "user_id": null
}
```
```

--------------------------------

### GET /v2/payout-batches/{payout_batch_id}

Source: https://docs.dots.dev/guides/batch-payouts

Retrieves the summary and status of a specific payout batch using its unique ID.

```APIDOC
## GET /v2/payout-batches/{payout_batch_id}

### Description
Retrieves the summary and status of a specific payout batch. Use this endpoint to monitor the progress of a batch after it has been submitted.

### Method
GET

### Endpoint
`/v2/payout-batches/{payout_batch_id}`

### Parameters
#### Path Parameters
- **payout_batch_id** (string) - Required - The unique identifier of the payout batch to retrieve.

### Request Example
```sh
curl --request GET \
  --url https://api.senddotssandbox.com/api/v2/payout-batches/e5d5863a-498d-4551-a3dc-e31012503f23 \
  --header 'Authorization: Basic <client_id:api_key>'
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the batch.
- **created** (string) - Timestamp when the batch was created.
- **status** (string) - Current status of the batch (e.g., `created`, `processing`, `paying_out`, `completed`).
- **idempotency_key** (string) - The idempotency key used for the batch submission.
- **metadata** (object | string) - Custom context attached to the batch.
- **items_processed** (integer) - Number of items processed so far.
- **items_succeeded** (integer) - Number of items that succeeded.
- **items_failed** (integer) - Number of items that failed.

#### Response Example
```json
{
  "id": "e5d5863a-498d-4551-a3dc-e31012503f23",
  "created": "2024-08-03T16:02:11.581Z",
  "status": "processing",
  "idempotency_key": "a7bb54d2-7342-4d13-a8aa-9d999753128b",
  "metadata": {
    "batch_type": "weekly_payouts",
    "week": "2024-08"
  },
  "items_processed": 50,
  "items_succeeded": 48,
  "items_failed": 2
}
```
```

--------------------------------

### API Environments Overview

Source: https://docs.dots.dev/overview/environments

This section details the two environments available for the Dots API: Sandbox and Production. It includes their descriptions and base URLs.

```APIDOC
## Dots API Environments

The Dots API provides two environments for integration:

### Sandbox Environment
- **Description**: Allows you to develop and test the integration without affecting live funds.
- **Base URL**: `https://pls.senddotssandbox.com/api`

### Production Environment
- **Description**: Used for live transactions after successfully testing the integration.
- **Base URL**: `https://api.dots.dev/api`

<Note>
  You must inform the Dots API version when performing a request. Currently, the V2 Dots API is available. Therefore, when performing a request to the Production environment, for example, you must use the following URL:

  * `https://api.dots.dev/api/v2`
</Note>
```

--------------------------------

### Production Environment Details

Source: https://docs.dots.dev/overview/environments

Information regarding the Production environment for live transactions, including access requests and API URL updates.

```APIDOC
## Production Environment

The Production environment is used for live transactions.

<Note>Dots team recommends switching to the Production environment only after completing all necessary integration tests.</Note>

To request access to the Production environment, contact us at [info@dots.dev](mailto:info@dots.dev) or through the Dots Dashboard, following the steps presented below:

1. Log in to the Dots Dashboard and toggle off the **View Sandbox Environment** in the upper left corner. A **PRODUCTION MODE** badge appears on the top of the page.
2. You need to set up a new application and generate new API keys.
3. If you're using Dots API, you must update the base API URL to `https://api.dots.dev/api/`.
```

--------------------------------

### Create User with Dots API

Source: https://docs.dots.dev/guides/white-labeled-payouts

This snippet demonstrates how to create a new user in the Dots system. It requires user details like name, email, and phone number, and accepts optional metadata. The response includes the unique user ID and status.

```sh
curl --request POST \
  --url https://pls.senddotssandbox.com/api/v2/users \
  --header 'Authorization: Basic cGtfZGV2X3lpYXF0aXkwOGdIb3gzR3pvUEo2RlFsaURkSDRnOnNrX2Rldl9nUDBHQjZCd1FmZmt3S2FEVkh0UmdTd0NPT2RNVA==' \
  --header 'Content-Type: application/json' \
  --data '{
    "first_name": "Bob",
    "last_name": "Loblaw",
    "email": "bob@bobloblaw.com",
    "country_code": "1",
    "phone_number": "4154332334",
    "metadata": {
      "internal_id": "user_121344"
    }
  }'
```

```json
{
  "email": "test@example.com",
  "first_name": "Bob",
  "id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4",
  "last_name": "Loblaw",
  "metadata": {
    "internal_id": "user_121344"
  },
  "phone_number": {
    "country_code": "55",
    "phone_number": "49933801774"
  },
  "status": "unverified",
  "verified": false
}
```

--------------------------------

### Create a Payout Link

Source: https://docs.dots.dev/guides/payout-links

Create a Payout Link using the API by providing the amount and other optional parameters. Requires App API Key and Client ID for authentication.

```APIDOC
## POST /api/v2/payout-links

### Description
Creates a Payout Link to facilitate payouts. Requires authentication with an App API Key and Client ID.

### Method
POST

### Endpoint
/api/v2/payout-links

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **user_id** (string) - Optional - The user's id.
- **payee** (string) - Optional - The payee.
- **amount** (integer) - **REQUIRED** - Amount to be paid in cents.
- **delivery** (object) - Optional - Delivery information.
  - **delivery.message** (string) - Optional - Message to send in the SMS message that is sent to the payee.
  - **delivery.method** (string) - Optional - Delivery method. Options: `sms`, `link`, `email`, `all`.
- **force_collect_compliance_information** (boolean) - Optional - Force the collection of 1099 or W-8 information.
- **tax_exempt** (boolean) - Optional - Payout links marked as `tax_exempt` will not be counted towards the 1099 threshold.
- **metadata** (object) - Optional - Set of key-value pairs that you can attach to an object. It is useful for storing additional information about the object in a structured format.
- **memo** (string) - Optional - Add a memo to the top of the Payout Link.
- **idempotency_key** (string) - Optional - Unique UUID key that prevents duplicate requests from being processed.
- **payout_fee_party** (string) - Optional - Overrides the setting for which party will pay fees on this payout.
- **additional_steps** (array) - Optional - Array of steps in the onboarding process. Options: `compliance`, `id-verification`, `background-check`, `manage-payments`, `manage-payouts`, `payout`, `redirect`.

### Request Example
```json
{
  "amount": 123,
  "idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the payout link.
- **amount** (integer) - The amount of the payout in cents.
- **status** (string) - The current status of the payout link.
- **url** (string) - The URL for the payout link.

#### Response Example
```json
{
  "id": "pl_a1b2c3d4e5f6",
  "amount": 123,
  "status": "created",
  "url": "https://example.com/payout/pl_a1b2c3d4e5f6"
}
```
```

--------------------------------

### Create a User

Source: https://docs.dots.dev/guides/white-labeled-payouts

Creates a new user in the Dots system. This is the first step before creating a payout. It requires user's first name, last name, email, country code, and phone number. Metadata can also be included.

```APIDOC
## POST /api/v2/users

### Description
Creates a new user in the Dots system. This is the first step before creating a payout. It requires user's first name, last name, email, country code, and phone number. Metadata can also be included.

### Method
POST

### Endpoint
https://pls.senddotssandbox.com/api/v2/users

### Parameters
#### Request Body
- **first_name** (string) - Required - The first name of the user.
- **last_name** (string) - Required - The last name of the user.
- **email** (string) - Required - The email address of the user.
- **country_code** (string) - Required - The country code for the user's phone number.
- **phone_number** (string) - Required - The phone number of the user.
- **metadata** (object) - Optional - Additional key-value pairs for custom information.
  - **internal_id** (string) - Optional - Example of metadata field for an internal ID.

### Request Example
```json
{
  "first_name": "Bob",
  "last_name": "Loblaw",
  "email": "bob@bobloblaw.com",
  "country_code": "1",
  "phone_number": "4154332334",
  "metadata": {
    "internal_id": "user_121344"
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the created user.
- **email** (string) - The email address of the user.
- **first_name** (string) - The first name of the user.
- **last_name** (string) - The last name of the user.
- **metadata** (object) - Metadata associated with the user.
- **phone_number** (object) - Phone number details.
  - **country_code** (string) - Country code of the phone number.
  - **phone_number** (string) - The phone number.
- **status** (string) - The current status of the user (e.g., 'unverified').
- **verified** (boolean) - Indicates if the user is verified.

#### Response Example
```json
{
  "email": "test@example.com",
  "first_name": "Bob",
  "id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4",
  "last_name": "Loblaw",
  "metadata": {
    "internal_id": "user_121344"
  },
  "phone_number": {
    "country_code": "55",
    "phone_number": "49933801774"
  },
  "status": "unverified",
  "verified": false
}
```
```

--------------------------------

### Example Metadata Object for Payments

Source: https://docs.dots.dev/references/metadata

This JSON object illustrates how metadata can be structured for payment-related requests. It includes keys for vendor ID, order ID, product category, and sales period, demonstrating its use for tracking and analysis.

```json
{
  "metadata": {
    "vendor_id": "vendor_567",
    "order_id": "order_890",
    "product_category": "Electronics",
    "sales_period": "Q2 2024"
  }
}
```

--------------------------------

### Create App

Source: https://docs.dots.dev/overview/authentication

This endpoint allows you to create a new app within your organization using an organization key. Ensure your authentication key is in the correct token format.

```APIDOC
## POST /api/v2/apps

### Description
Creates a new app within your organization.

### Method
POST

### Endpoint
https://api.dots.dev/api/v2/apps

### Parameters
#### Headers
- **Authorization** (string) - Required - Your authentication token in the format 'Basic <token>'.
- **Content-Type** (string) - Required - Must be 'application/json'.

#### Request Body
- **name** (string) - Required - The name of the app to be created.

### Request Example
```json
{
  "name": "<app_name>"
}
```

### Response
#### Success Response (200 or 201)
- **id** (string) - The unique identifier of the newly created app.
- **name** (string) - The name of the created app.
- **organization_id** (string) - The ID of the organization the app belongs to.

#### Response Example
```json
{
  "id": "app_xxxxxxxxxxxxxx",
  "name": "My New App",
  "organization_id": "org_yyyyyyyyyyyyyy"
}
```
```

--------------------------------

### Create Batch Payouts Request (cURL)

Source: https://docs.dots.dev/guides/batch-payouts

This cURL command demonstrates how to create a batch payout request. It includes batch-level metadata and a list of individual payout items, each with its own user ID, amount, platform, idempotency key, and other optional fields. Ensure 'fund' is set to true for all items.

```sh
curl --request POST \
    --url https://api.senddotssandbox.com/api/v2/payout-batches \
    --header 'Authorization: Basic <client_id:api_key>' \
    --header 'Content-Type: application/json' \
    --data '{ \
      "idempotency_key": "a7bb54d2-7342-4d13-a8aa-9d999753128b", \
      "metadata": { \
        "batch_type": "weekly_payouts", \
        "week": "2024-08" \
      }, \
      "items": [ \
        { \
          "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5", \
          "amount": 1000, \
          "platform": "paypal", \
          "idempotency_key": "c3d4e5f6-g7h8-i9j0-k1l2-m3n4o5p6q7r8", \
          "fund": true, \
          "tax_exempt": false, \
          "metadata": { \
            "invoice_id": "INV-123" \
          } \
        }, \
        { \
          "user_id": "b269451c-9625-5452-c9db-171ee559b2b6", \
          "amount": 2500, \
          "platform": "ach", \
          "account_id": "c369451c-a725-6552-d0ec-272ff669c3c7", \
          "idempotency_key": "d4e5f6g7-h8i9-j0k1-l2m3-n4o5p6q7r8s9", \
          "fund": true, \
          "tax_exempt": false \
        } \
      ] \
    }'
```

--------------------------------

### Create App using cURL

Source: https://docs.dots.dev/overview/authentication

This snippet demonstrates how to create a new app within your organization using a cURL command. It requires an Authorization token and sends app details in JSON format. The `Api-App-Id` header is not needed for app creation itself, but is required for subsequent operations on behalf of the app.

```cURL
curl --request POST \
  --url https://api.dots.dev/api/v2/apps \
  --header 'Authorization: Basic <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "<app_name>",
  }'
```

--------------------------------

### Create Payout Request and Response (Shell/JSON)

Source: https://docs.dots.dev/guides/white-labeled-payouts

This snippet illustrates how to initiate a payout from a user's wallet using the Dots.dev API. It includes the cURL request specifying user ID, amount, and platform, along with a JSON response confirming the payout's creation.

```sh
curl --request POST \
        --url https://api.dots.dev/api/v2/payouts \
        --header 'Authorization: Basic cGtfZGV2X0g3V0tFOXlTRGhqeW91dFZBNEk3RkxhVkUzaWg1OnNrX2Rldl9lekFPNXA0WUNJeld6RWgwam5ubHFrODRkQ3ZFOQ==' \
        --header 'Content-Type: application/json' \
        --data '{ \
        "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4", \
        "amount": 1000, \
        "platform": "default" \
      }'
```

```json
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created": "2023-11-07T05:31:56Z",
  "user_id": "fc54b468-bbb2-403f-be36-5627a8e3c7a4",
  "status": "created",
  "type": "refill",
  "amount": 1000,
  "external_data": {
    "account_id": "<string>",
    "external_id": "<string>",
    "platform": "ach"
  },
  "transactions": [
    {
      "id": 123,
      "amount": 1000,
      "created": "2023-11-07T05:31:56Z",
      "source_name": "<string>",
      "destination_name": "<string>",
      "type": "balance",
      "metadata": "<string>"
    }
  ]
}
```

--------------------------------

### Create User with IP Address Tracking (Bash)

Source: https://docs.dots.dev/references/ip-address-tracking

Demonstrates how to create a user with IP address tracking enabled by including the 'Dots-User-IP' header in a cURL request. This helps Dots log and analyze the user's IP for fraud detection. The request requires an Authorization header and specifies user details in JSON format.

```bash
curl --request POST \
  --url https://api.dots.dev/api/v2/users \
  --header 'Authorization: <authorization>' \
  --header 'Dots-User-IP: 192.0.2.0' \
  --header 'Content-Type: application/json' \
  --data '{
  "first_name": "Bob",
  "last_name": "Loblaw",
  "email": "bob@bobloblaw.com",
  "country_code": "1",
  "phone_number": "4154332334",
  "metadata": {
    "internal_id": "user_121344"
  }
}'
```

--------------------------------

### Retrieve Dots Flow Information (cURL)

Source: https://docs.dots.dev/guides/flow-payouts

This snippet shows how to retrieve details of a specific Dots Flow using its ID. This is typically done after a user has completed the onboarding process. The response includes the 'user_id', which is essential for creating payouts. Authentication with App credentials is required.

```sh
curl --request GET \
  --url https://pls.senddotssandbox.com/api/v2/flows/b3293101-35ef-451a-aad4-881da3697c2f \
  --header 'Authorization: Basic cGtfZGV2X0g3V0tFOXlTRGhqeW91dFZBNEk3RkxhVkUzaWg1OnNrX2Rldl9lekFPNXA0WUNJeld6RWgwam5ubHFrODRkQ3ZFOQ=='
```

```json
{
  "completed_steps": [],
  "created": "2024-07-11T21:10:30.846081",
  "id": "b3293101-35ef-451a-aad4-881da3697c2f",
  "link": "https://my-sandbox.dots.dev/flow/b3293101-35ef-451a-aad4-881da3697c2f",
  "metadata": null,
  "payout_link_id": null,
  "steps": [
    "compliance"
  ],
  "user_id": "f33919ae-6793-41bd-b512-1ad3c19f4ecb"
}
```

--------------------------------

### Payout Flow

Source: https://docs.dots.dev/guides/flow-payouts

Allows the user to initiate a payout to their preferred payout method.

```APIDOC
## POST /websites/dots_dev/flows/payout

### Description
Enables a user to initiate a payout to their selected payout method.

### Method
POST

### Endpoint
/websites/dots_dev/flows/payout

### Parameters
#### Query Parameters
- **payout_fee_party** (string) - Optional - Defines who pays the fee for the payout. Possible values: `platform`, `user`.

#### Request Body
- **user_id** (string) - Optional - The ID of the user initiating the payout. If not provided, onboarding is added.
- **payout_method_id** (string) - Required - The ID of the payout method to use.
- **amount** (number) - Required - The amount to be paid out.

### Request Example
```json
{
  "user_id": "user101",
  "payout_method_id": "payout_method_abc",
  "amount": 100.50
}
```

### Response
#### Success Response (200)
- **payout_id** (string) - The ID of the initiated payout.
- **status** (string) - The status of the payout (e.g., `pending`, `processing`, `completed`).

#### Response Example
```json
{
  "payout_id": "payout_xyz789",
  "status": "pending"
}
```
```

--------------------------------

### Webhook Signing

Source: https://docs.dots.dev/references/webhooks

Instructions for verifying webhook authenticity. It's crucial to verify payloads to ensure they originate from the expected source.

```APIDOC
## Webhook Signing

### Description
Find the instructions to verify webhooks [here](https://docs.svix.com/receiving/verifying-payloads/why)

### Verification Process
To ensure the security and integrity of the data received via webhooks, it is essential to verify their authenticity. This typically involves using a shared secret to sign and verify the webhook payloads. Refer to the provided documentation link for detailed instructions on implementing webhook signature verification.
```

--------------------------------

### List Historical Payout Batches (Shell)

Source: https://docs.dots.dev/guides/batch-payouts

Retrieves a paginated list of historical payout batches created by your application. The `limit`, `starting_after`, and `ending_before` query parameters can be used to efficiently page through older batch entries. This is useful for auditing and managing past payout operations.

```sh
curl --request GET \
  --url "https://api.senddotssandbox.com/api/v2/payout-batches?limit=10" \
  --header 'Authorization: Basic <client_id:api_key>'
```

--------------------------------

### Generate Basic Tokens for Dots API Authentication

Source: https://docs.dots.dev/overview/authentication

Demonstrates the generation of Base64 encoded tokens for Dots API authentication. This includes formats for both client-side and server-side requests, using the client_id and optionally the api_key. The output is a Base64 encoded string.

```javascript
BASE64_ENCODE(ABC123:) -> QUJDMTIzOg==
```

```javascript
BASE64_ENCODE(ABC123:DEF456) -> QUJDMTIzOkRFRjQ1Ng==
```

--------------------------------

### Create User

Source: https://docs.dots.dev/references/users

Creates a Dots user if one does not exist based on the provided phone number. The user will then need to be verified via a one-time code.

```APIDOC
## POST /v2/users

### Description
Creates a Dots user if one does not exist based on phone number. The user must then be verified through a one-time code sent over text-message.

### Method
POST

### Endpoint
/v2/users

### Parameters
#### Request Body
- **phone_number** (string) - Required - The phone number of the user.

### Request Example
```json
{
  "phone_number": "+11234567890"
}
```

### Response
#### Success Response (201)
- **user_id** (string) - The unique identifier for the created user.

#### Response Example
```json
{
  "user_id": "usr_123abc456def"
}
```
```

--------------------------------

### Create Payout Link API Request (cURL)

Source: https://docs.dots.dev/guides/payout-links

This snippet demonstrates how to create a Payout Link using a cURL request to the API. It includes the necessary headers for authorization and content type, along with a JSON payload containing the required 'amount' and 'idempotency_key'.

```sh
curl --request POST \
--url https://pls.senddotssandbox.com/api/v2/payout-links \
--header 'Authorization: Basic <token>' \
--header 'Content-Type: application/json' \
--data '{ \
"amount": 123, \
"idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a" \
}'
```

--------------------------------

### Manage Payments Flow

Source: https://docs.dots.dev/guides/flow-payouts

Enables users to connect a bank account for ACH payments.

```APIDOC
## POST /websites/dots_dev/flows/manage-payments

### Description
Allows users to connect a bank account for ACH (Automated Clearing House) payments.

### Method
POST

### Endpoint
/websites/dots_dev/flows/manage-payments

### Parameters
#### Query Parameters
- **hide_continue_button** (boolean) - Optional - Hides the continue button after the flow is completed.

#### Request Body
- **user_id** (string) - Optional - The ID of the user managing payments. If not provided, onboarding is added.

### Request Example
```json
{
  "user_id": "user789"
}
```

### Response
#### Success Response (200)
- **message** (string) - A success message indicating the bank account has been connected.

#### Response Example
```json
{
  "message": "Bank account connected successfully for ACH payments."
}
```
```