### Environment Variables for Puzzle API Credentials

Source: https://puzzle-api.readme.io/docs/getting-started

Example environment variables for storing Puzzle API client ID, client secret, and connection key. These are essential for authentication and constructing API request URLs.

```env
PUZZLE_CLIENT_ID=cid_test_123
PUZZLE_CLIENT_SECRET=sk_test_123
PUZZLE_CONNECTION_KEY=acme
```

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

### POST /oauth/token

Source: https://puzzle-api.readme.io/docs/getting-started

Exchanges an authorization code or a refresh token for a valid access token to authenticate API requests.

```APIDOC
## POST /oauth/token

### Description
Exchanges an authorization code (received after user consent) or a refresh token for an access token. This endpoint is used both for the initial token acquisition and for refreshing expired tokens.

### Method
POST

### Endpoint
https://api.puzzle.io/oauth/token

### Parameters
#### Request Body
- **client_id** (string) - Required - Your application's unique client identifier.
- **client_secret** (string) - Required - Your application's client secret.
- **redirect_uri** (string) - Required - The URI to redirect to after authorization.
- **code** (string) - Optional - The authorization code received from the redirect (required for authorization_code grant).
- **refresh_token** (string) - Optional - The refresh token (required for refresh_token grant).
- **grant_type** (string) - Required - Must be either "authorization_code" or "refresh_token".

### Request Example
{
  "client_id": "{{PUZZLE_CLIENT_ID}}",
  "client_secret": "{{PUZZLE_CLIENT_SECRET}}",
  "redirect_uri": "https://example.com/callback",
  "code": "123456",
  "grant_type": "authorization_code"
}

### Response
#### Success Response (200)
- **access_token** (string) - The token used to authenticate API requests.
- **refresh_token** (string) - Token used to obtain new access tokens.
- **scope** (string) - Authorized permissions.
- **expires_in** (integer) - Token lifetime in seconds.
- **token_type** (string) - Usually "Bearer".

#### Response Example
{
  "access_token": "eyJhbGciOiJIUzI1Ni...",
  "refresh_token": "3aecd59e7834be2c637a9ee260f24wIAbJunx6Gy",
  "scope": "read:company offline_access",
  "expires_in": 86400,
  "token_type": "Bearer"
}
```

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

### Company Connection Management and Categorization Links

Source: https://puzzle-api.readme.io/docs/getting-started

Provides URLs to direct users to pages for managing company connections and categorizing transactions. These are not API endpoints but are essential for user interaction.

```APIDOC
## User Redirection URLs

### Description
These URLs are used to redirect users to specific pages within the Puzzle application for managing their company's financial connections or categorizing transactions. They are not direct API endpoints but are critical for user experience.

### Categorize Transactions
Direct users to this URL to allow them to categorize their company's transactions. It's recommended to open this in a new tab.

**URL Format:**
```
https://staging.southparkdata.com/connect/{{PUZZLE_CONNECTION_KEY}}/categorize
```

### Manage Institution Connections
Direct users to this URL if their institution connections are `Disconnected` and require reconnection. It's recommended to open this in a new tab.

**URL Format:**
```
https://staging.southparkdata.com/connect/{{PUZZLE_CONNECTION_KEY}}/manage
```

**Note:** Replace `{{PUZZLE_CONNECTION_KEY}}` with the actual connection key provided during the authentication flow.
```

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

### Get Current User Information (HTTP)

Source: https://puzzle-api.readme.io/docs/getting-started

Fetches the current user's information, including the company IDs they have access to. Requires an Authorization header with a Bearer token. The response contains the user's ID and a list of companies with their IDs, names, and statuses.

```http
GET https://staging.southparkdata.com/rest/v0/me
Authorization: Bearer eyJhbGci...
```

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

### Get Current User Information

Source: https://puzzle-api.readme.io/docs/getting-started

Fetches the current user's information, including a list of company IDs they have access to. This is typically used after authentication to identify accessible companies.

```APIDOC
## GET /rest/v0/me

### Description
Retrieves the current authenticated user's information and a list of companies they have access to. This is a crucial step after user authentication to identify accessible company data.

### Method
GET

### Endpoint
https://staging.southparkdata.com/rest/v0/me

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```http
GET https://staging.southparkdata.com/rest/v0/me
Authorization: Bearer <YOUR_ACCESS_TOKEN>
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the user.
- **companies** (array) - A list of companies the user has access to.
  - **id** (string) - The unique identifier for the company.
  - **name** (string) - The name of the company.
  - **status** (string) - The current status of the company data (e.g., "Ready", "Syncing").

#### Response Example
```json
{
  "id": "us_5lmKFvtNBwvLyX6f7qwNGx",
  "companies": [
    {
      "id": "co_1zK3taSboLa8Lr158Havdq",
      "name": "Flourish and Blotts",
      "status": "Ready"
    },
    {
      "id": "co_1odgEBwK0lFZc1h69cI61G",
      "name": "The Leaky Cauldron",
      "status": "Syncing"
    }
  ]
}
```
```

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

### Example Bookkeeping Request Creation (JSON)

Source: https://puzzle-api.readme.io/docs/bookkeeping

This JSON payload demonstrates how to create or update bookkeeping requests for a transaction using the POST /requests endpoint. It shows how to specify different request types and their statuses, as well as add messages.

```json
{
  "transactionId": "txn_12345",
  "requests": {
    "categoryReview": {
      "requestedUserId": "user_67890",
      "status": "Open"
    },
    "documentationReview": {
      "status": "Completed"
    },
    "messages": [
      {
        "message": "A first message"
      },
      {
        "message": "And another one!"
      }
    ]
  }
}
```

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

### Import Transactions Workflow

Source: https://puzzle-api.readme.io/docs/transactions

Guides users through the process of importing new transactions into existing or new accounts.

```APIDOC
## Import Transactions Workflow

### Description
This workflow outlines the steps for importing transactions, differentiating between new and existing accounts.

### New Account Setup
1. **Create Financial Account**: Initiate the creation of a new financial account.
2. **Create Account Balance**: Set an initial balance for the newly created account. Refer to the **Account Balance Guide** for details on trending balances.

### Existing Accounts
1. **Create Transactions**: Use this endpoint to add up to 500 transactions in a single request.
2. **Create Document Attachment**: For each transaction requiring a document, call this endpoint to attach it.
```

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

### POST /onboarding

Source: https://puzzle-api.readme.io/docs/copy-of-one-click-onboarding-w-journal-entry-synch

Retrieves a prefilled onboarding URL for users who already exist in the system.

```APIDOC
## POST /onboarding

### Description
Returns a URL to redirect the user to complete company creation. The user must log in with the same email used during initial registration.

### Method
POST

### Endpoint
/onboarding

### Request Body
- **name** (string) - Required - Company name.
- **type** (string) - Required - Industry type.
- **revenueModel** (string) - Required - Revenue model.
- **timeZone** (string) - Required - Company timezone.
- **currentUserRole** (string) - Required - User role.
- **coaType** (string) - Required - Chart of accounts type.
- **orgType** (string) - Required - Organization type.

### Request Example
{
  "name": "Test Company",
  "type": "VirtualGoods",
  "revenueModel": "AnnualSubscription",
  "timeZone": "US/Alaska",
  "currentUserRole": "Founder",
  "coaType": "saas",
  "orgType": "LLC"
}

### Response
#### Success Response (200)
- **url** (string) - Redirect URL for onboarding.

#### Response Example
{
  "url": "https://..."
}
```

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

### JSON Response for Refreshed OAuth2 Access Token

Source: https://puzzle-api.readme.io/docs/getting-started

Example JSON response from the Puzzle API after successfully refreshing an access token. It provides a new access token, scope, expiration time, and token type, enabling continued authenticated requests.

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "scope": "read:company offline_access",
  "expires_in": 86400,
  "token_type": "Bearer"
}
```

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

### POST /onboarding

Source: https://puzzle-api.readme.io/docs/one-click-onboarding

Generates a prefilled onboarding URL for existing users who do not yet have a company associated with their account.

```APIDOC
## POST /onboarding

### Description
Returns a URL to redirect the user to complete company creation. The user must log in with the same email used in the initial Create Company request.

### Method
POST

### Endpoint
/onboarding

### Request Body
- **name** (string) - Required - Company name.
- **type** (string) - Required - Industry type.
- **revenueModel** (string) - Required - Business revenue model.
- **timeZone** (string) - Required - Company timezone.
- **currentUserRole** (string) - Required - User role in the company.
- **coaType** (string) - Required - Chart of accounts type.
- **orgType** (string) - Required - Organization type.

### Request Example
{
  "name": "Test Company",
  "type": "VirtualGoods",
  "revenueModel": "AnnualSubscription",
  "timeZone": "US/Alaska",
  "currentUserRole": "Founder",
  "coaType": "saas",
  "orgType": "LLC"
}

### Response
#### Success Response (200)
- **url** (string) - The redirect URL for the user to complete onboarding.

#### Response Example
{
  "url": "https://..."
}
```

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

### JSON Response for OAuth2 Access Token and Refresh Token

Source: https://puzzle-api.readme.io/docs/getting-started

Example JSON response from the Puzzle API after a successful request for an access token. It includes the access token, refresh token, scope, expiration time, and token type, which are necessary for subsequent API interactions.

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "refresh_token": "3aecd59e7834be2c637a9ee260f24wIAbJunx6Gy",
  "scope": "read:company offline_access",
  "expires_in": 86400,
  "token_type": "Bearer"
}
```

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

### Create Company API Request and Responses

Source: https://puzzle-api.readme.io/docs/one-click-onboarding

Demonstrates the POST /company endpoint request body and the various response scenarios (200 OK, 400 User Already Exists, 400 User and Company Already Exists). This is the initial step for all onboarding flows.

```json
{
  "user": {
    "email": "test-user@company.io",
    "firstName": "Test",
    "lastName": "User"
  },
  "company": {
    "name": "Test Company",
    "type": "VirtualGoods",
    "revenueModel": "AnnualSubscription",
    "timeZone": "US/Alaska",
    "currentUserRole": "Founder",
    "coaType": "saas",
    "orgType": "LLC"
  }
}
```

```json
{
  "companyId": "co_xxx",
  "userId": "user_xxx",
  "setPasswordUrl": "https://..."
}
```

```json
{
  "errors": [
    {
      "message": "User already exists in Puzzle system",
      "code": "USER_ALREADY_EXISTS"
    }
  ]
}
```

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

### POST /company

Source: https://puzzle-api.readme.io/docs/one-click-onboarding

Creates a new company, user, and integration connection. This is the primary entry point for the onboarding workflow.

```APIDOC
## POST /company

### Description
Creates a company, user, and integration connection. Returns a setPasswordUrl to allow the user to set a password which completes their Puzzle account setup.

### Method
POST

### Endpoint
/company

### Request Body
- **user** (object) - Required - User details including email, firstName, and lastName.
- **company** (object) - Required - Company details including name, type, revenueModel, timeZone, currentUserRole, coaType, and orgType.

### Request Example
{
  "user": {
    "email": "test-user@company.io",
    "firstName": "Test",
    "lastName": "User"
  },
  "company": {
    "name": "Test Company",
    "type": "VirtualGoods",
    "revenueModel": "AnnualSubscription",
    "timeZone": "US/Alaska",
    "currentUserRole": "Founder",
    "coaType": "saas",
    "orgType": "LLC"
  }
}

### Response
#### Success Response (200)
- **companyId** (string) - Unique identifier for the created company.
- **userId** (string) - Unique identifier for the created user.
- **setPasswordUrl** (string) - URL for the user to set their account password.

#### Response Example
{
  "companyId": "co_xxx",
  "userId": "user_xxx",
  "setPasswordUrl": "https://..."
}
```

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

### Prefilled Onboarding Request

Source: https://puzzle-api.readme.io/docs/one-click-onboarding

Used in Scenario B to redirect existing users to complete their company creation. Requires the same company details provided during the initial creation attempt.

```json
{
  "name": "Test Company",
  "type": "VirtualGoods",
  "revenueModel": "AnnualSubscription",
  "timeZone": "US/Alaska",
  "currentUserRole": "Founder",
  "coaType": "saas",
  "orgType": "LLC"
}
```

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

### Prefilled Onboarding

Source: https://puzzle-api.readme.io/docs/copy-of-one-click-onboarding-w-journal-entry-synch

Directs users to complete company creation when they exist as a user but not within a company. This is part of Scenario B.

```APIDOC
## GET /onboarding/prefilled

### Description
This endpoint is used in Scenario B to allow an existing user (who does not have a company) to complete their company setup. The user should be redirected to this URL.

### Method
GET

### Endpoint
/onboarding/prefilled

### Parameters
#### Query Parameters
- **token** (string) - Required - An authentication token provided after the initial company creation attempt.

### Response
#### Success Response (200 OK)
- Redirects the user to the Puzzle onboarding interface to complete company creation.

### Request Example
```
GET /onboarding/prefilled?token=some_auth_token
```
```

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

### Retrieve Company Financial Summary

Source: https://puzzle-api.readme.io/docs/getting-started

Fetches the financial summary for a specific company. This endpoint may return a RESOURCE_PROCESSING error if the company's data is still being ingested.

```APIDOC
## GET /rest/v0/company/{companyId}

### Description
Retrieves the financial summary and related metadata for a specific company. If the company's data is still being processed after initial connection, a `RESOURCE_PROCESSING` error (409) may be returned.

### Method
GET

### Endpoint
https://staging.southparkdata.com/rest/v0/company/{companyId}

### Parameters
#### Path Parameters
- **companyId** (string) - Required - The unique identifier of the company.

#### Query Parameters
- **id** (string) - Required - The unique identifier of the company. (Note: This appears redundant with the path parameter in the example, but is included as per the provided text).

#### Request Body
None

### Request Example
```http
GET https://staging.southparkdata.com/rest/v0/company/co_1zK3taSboLa8Lr158Havdq?id=co_1zK3taSboLa8Lr158Havdq
Authorization: Bearer <YOUR_ACCESS_TOKEN>
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the company.
- **institutionConnections** (array) - A list of the company's institution connections.
  - **id** (string) - The unique identifier for the institution connection.
  - **status** (string) - The status of the connection (e.g., "Ok", "Disconnected").
  - **institution** (object) - Information about the financial institution.
    - **id** (string) - The unique identifier for the institution.
    - **name** (string) - The name of the institution.
  - **accounts** (array) - A list of accounts associated with the connection.
  - **lastSyncedAt** (string) - The timestamp of the last successful data sync.
  - **createdAt** (string) - The timestamp when the connection was created.
- **financialSummary** (object) - An object containing the company's financial summary.
  - **status** (string) - The status of the financial summary (e.g., "Ready").
  - **metrics** (object) - Key financial metrics.
    - **cashOutDate** (string) - Estimated cash out date.
    - **runway** (integer) - Estimated runway in days.
    - **fundraiseDate** (string) - Estimated fundraise date.
    - **lastMonthOperatingBurn** (object) - Operating burn for the last month.
      - **amount** (string) - The amount of the burn.
      - **currency** (string) - The currency of the amount.
    - **annualAvgFullyLoadedSalaryCostPerEmployee** (object) - Average fully loaded salary cost per employee annually.
    - **annualAvgSalaryCostPerEmployee** (object) - Average salary cost per employee annually.
    - **lastMonthAvgFullyLoadedSalaryCostPerEmployee** (object) - Average fully loaded salary cost per employee for the last month.
    - **lastMonthAvgSalaryCostPerEmployee** (object) - Average salary cost per employee for the last month.
- **metadata** (object) - Additional metadata about the company's data.
  - **dataCompletenessLevel** (string) - A qualitative assessment of data completeness (e.g., "High", "Medium", "Low").
  - **categorization** (object) - Information about transaction categorization.
    - **percentDollarVolumeCategorized** (number) - The percentage of total dollar volume that has been categorized.

#### Response Example
```json
{
  "id": "co_1zK3taSboLa8Lr158Havdq",
  "institutionConnections": [
    {
      "id": "ic_2qY9COoAhfMrsH7mCyh86T",
      "status": "Ok",
      "institution": {
        "id": "fi_2qY9COoAhfMrsH7mCyh86T",
        "name": "Silicon Valley Bank"
      },
      "accounts": [
        {}
      ],
      "lastSyncedAt": "2021-10-24T02:17:58.787Z",
      "createdAt": "2021-08-30T04:07:21.656Z"
    }
  ],
  "financialSummary": {
    "status": "Ready",
    "metrics": {
      "cashOutDate": "18-12-2023",
      "runway": 18,
      "fundraiseDate": "18-06-2023",
      "lastMonthOperatingBurn": {
        "amount": "388587.46",
        "currency": "USD"
      },
      "annualAvgFullyLoadedSalaryCostPerEmployee": {
        "amount": "132349.30",
        "currency": "USD"
      },
      "annualAvgSalaryCostPerEmployee": {
        "amount": "117094.25",
        "currency": "USD"
      },
      "lastMonthAvgFullyLoadedSalaryCostPerEmployee": {
        "amount": "172329.",
        "currency": "USD"
      },
      "lastMonthAvgSalaryCostPerEmployee": {
        "amount": "167094.25",
        "currency": "USD"
      }
    }
  },
  "metadata": {
    "dataCompletenessLevel": "High",
    "categorization": {
      "percentDollarVolumeCategorized": 0.92
    }
  }
}
```
```

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

### POST /company

Source: https://puzzle-api.readme.io/docs/copy-of-one-click-onboarding-w-journal-entry-synch

Initializes a new company, user, and integration connection. Returns a URL for the user to set their password.

```APIDOC
## POST /company

### Description
Creates a company, user, and integration connection. Returns a setPasswordUrl to allow the user to set a password which completes their Puzzle account setup.

### Method
POST

### Endpoint
/company

### Request Body
- **user** (object) - Required - User details including email, firstName, and lastName.
- **company** (object) - Required - Company details including name, type, revenueModel, timeZone, currentUserRole, coaType, and orgType.

### Request Example
{
  "user": {
    "email": "test-user@company.io",
    "firstName": "Test",
    "lastName": "User"
  },
  "company": {
    "name": "Test Company",
    "type": "VirtualGoods",
    "revenueModel": "AnnualSubscription",
    "timeZone": "US/Alaska",
    "currentUserRole": "Founder",
    "coaType": "saas",
    "orgType": "LLC"
  }
}

### Response
#### Success Response (200)
- **companyId** (string) - Unique identifier for the company.
- **userId** (string) - Unique identifier for the user.
- **setPasswordUrl** (string) - URL to complete account setup.

#### Response Example
{
  "companyId": "co_xxx",
  "userId": "user_xxx",
  "setPasswordUrl": "https://..."
}
```

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

### Shared Key Authentication Header

Source: https://puzzle-api.readme.io/docs/one-click-onboarding

Illustrates how to use Shared Key authentication for server-to-server communication. This method involves setting specific request headers for client identification and authorization.

```HTTP
GET /some/endpoint HTTP/1.1
Host: puzzle.example.com
puzzle-client-id: YOUR_CLIENT_ID
Authorization: Bearer YOUR_CLIENT_SECRET
```

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

### Shared Key Authentication

Source: https://puzzle-api.readme.io/docs/one-click-onboarding

Authentication method for server-to-server communication where no user interaction is required.

```APIDOC
## Shared Key Authentication Headers

### Description
Use these headers for server-to-server requests. Note: This method cannot be used with the /me endpoint.

### Headers
- **puzzle-client-id** (string) - Required - Your unique client ID.
- **Authorization** (string) - Required - Set to 'Bearer {{clientSecret}}'.
```

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

### Categorize Transactions URL

Source: https://puzzle-api.readme.io/docs/getting-started

Provides a URL to direct users to categorize their transactions. This is recommended when data completeness is low or medium to improve metric confidence. The URL includes a placeholder for the Puzzle connection key.

```text
https://staging.southparkdata.com/connect/{{PUZZLE_CONNECTION_KEY}}/categorize
```

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

### OAuth 2.0 Authentication

Source: https://puzzle-api.readme.io/docs/one-click-onboarding

The preferred authentication method for user-facing applications. Requires a user login and approval flow.

```APIDOC
## GET /authorize

### Description
Initiates the OAuth 2.0 authorization flow to obtain a temporary authorization code.

### Method
GET

### Endpoint
/authorize

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The unique identifier for your application.
- **redirect_uri** (string) - Required - The URI to redirect to after user approval.

---

## POST /access-token

### Description
Exchanges an authorization code for a bearer access token.

### Method
POST

### Endpoint
/access-token

### Request Body
- **code** (string) - Required - The authorization code received from the redirect URI.

### Response
#### Success Response (200)
- **access_token** (string) - The bearer token to be used in the Authorization header.
```

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

### Manage Company Connections URL

Source: https://puzzle-api.readme.io/docs/getting-started

Provides a URL to direct users to manage their institution connections. This is necessary when a connection status is 'Disconnected' to allow re-importing data. The URL includes a placeholder for the Puzzle connection key.

```text
https://staging.southparkdata.com/connect/{{PUZZLE_CONNECTION_KEY}}/manage
```

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

### Create Company Endpoint

Source: https://puzzle-api.readme.io/docs/copy-of-one-click-onboarding-w-journal-entry-synch

Creates a new company and user, returning a URL for the user to set their password. The email must be unique. Handles scenarios for existing users and companies.

```json
{
  "user": {
    "email": "test-user at company.io",
    "firstName": "Test",
    "lastName": "User"
  },
  "company": {
    "name": "Test Company",
    "type": "VirtualGoods",
    "revenueModel": "AnnualSubscription",
    "timeZone": "US/Alaska",
    "currentUserRole": "Founder",
    "coaType": "saas",
    "orgType": "LLC"
  }
}
```

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

### Retrieve Company Financial Summary (HTTP)

Source: https://puzzle-api.readme.io/docs/getting-started

Retrieves the financial summary for a specific company using its ID. This endpoint is used after a company is ready and data has been processed. It returns detailed financial metrics and connection statuses. Requires an Authorization header.

```http
GET https://staging.southparkdata.com/rest/v0/company/co_1zK3taSboLa8Lr158Havdq?id=co_1zK3taSboLa8Lr158Havdq
Authorization: Bearer eyJhbGci...
```

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

### OAuth 2.0 Authentication Flow

Source: https://puzzle-api.readme.io/docs/one-click-onboarding

Demonstrates the OAuth 2.0 authentication flow for scenarios requiring user authorization. This involves obtaining an authorization code and exchanging it for a bearer token. It requires a logged-in user.

```HTTP
POST /authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI HTTP/1.1
Host: puzzle.example.com

POST /access_token?code=AUTHORIZATION_CODE HTTP/1.1
Host: puzzle.example.com
Authorization: Bearer YOUR_CLIENT_SECRET
```

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

### HTTP POST Request to Refresh Expired OAuth2 Access Token

Source: https://puzzle-api.readme.io/docs/getting-started

An HTTP POST request to the Puzzle API's token endpoint to refresh an expired access token using a refresh token. This allows for continued access to the API without requiring the user to re-authorize the application.

```http
POST https://staging.southparkdata.com/oauth/token
Content-Type: application/json

{
  "client_id": "{{PUZZLE_CLIENT_ID}}",
  "client_secret": "{{PUZZLE_CLIENT_SECRET}}",
  "redirect_uri": "https://example.com/callback",
  "refresh_token": "3aecd59e7834be2c637a9ee260f24wIAbJunx6Gy",
  "grant_type": "refresh_token"
}
```

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

### HTTP POST Request to Obtain OAuth2 Access Token

Source: https://puzzle-api.readme.io/docs/getting-started

An HTTP POST request to the Puzzle API's token endpoint to exchange an authorization code for an access token and refresh token pair. This is a crucial step in the OAuth2 authentication flow, requiring client credentials and the authorization code.

```http
POST https://staging.southparkdata.com/oauth/token
Content-Type: application/json

{
  "client_id": "{{PUZZLE_CLIENT_ID}}",
  "client_secret": "{{PUZZLE_CLIENT_SECRET}}",
  "redirect_uri": "https://example.com/callback",
  "code": "123456",
  "grant_type": "authorization_code"
}
```

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

### HTML Link to Authorize Puzzle Account Connection

Source: https://puzzle-api.readme.io/docs/getting-started

An HTML anchor tag used to direct users to the Puzzle authorization URL. This initiates the OAuth2 flow, allowing users to grant your application access to their Puzzle data. It includes parameters like client ID, redirect URI, response type, and state for security.

```html
<a
  href="https://staging.southparkdata.com/oauth/authorize
    ?client_id={{PUZZLE_CLIENT_ID}}
    &redirect_uri=https://example.com/callback
    &response_type=code
    &state=a8e6a88f137b4b1a921155c8157907f3"
>
  Connect your Puzzle account
</a>
```

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

### Create Account Balance

Source: https://puzzle-api.readme.io/docs/transactions

Creates a reference point in time for an account balance.

```APIDOC
## Create Account Balance

### Description
Creates a reference point in time for an account balance, essential for tracking financial standing.

### Method
POST

### Endpoint
`/accounts/{accountId}/balances`

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The ID of the account for which to create the balance.

#### Request Body
- **balance** (number) - Required - The balance amount. Trending towards positive.
- **asOf** (string) - Required - The date and time the balance is effective (ISO 8601 format).

### Request Example
```json
{
  "balance": 1000.50,
  "asOf": "2023-10-27T10:00:00Z"
}
```

### Response
#### Success Response (201 Created)
- **balanceId** (string) - The unique identifier for the created balance record.
- **accountId** (string) - The ID of the account.
- **balance** (number) - The recorded balance amount.
- **asOf** (string) - The effective date and time of the balance.

#### Response Example
```json
{
  "balanceId": "bal_abcde",
  "accountId": "acc_12345",
  "balance": 1000.50,
  "asOf": "2023-10-27T10:00:00Z"
}
```
```

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

### GET /requests

Source: https://puzzle-api.readme.io/docs/bookkeeping

Retrieves a list of bookkeeping requests associated with transactions and integrations. This endpoint returns requests with a common structure including ID, type, status, user information, and transaction ID.

```APIDOC
## GET /requests

### Description
Retrieves a list of bookkeeping requests. These requests can be of type Category Review, Documentation, Message, or Integration. The response includes details about the request, associated users, and transaction if applicable.

### Method
GET

### Endpoint
/requests

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **requests** (array) - An array of request objects.
  - **id** (string) - Unique identifier for the request.
  - **type** (string) - The type of request (e.g., "CategoryReview", "Documentation", "Message", "Integration").
  - **status** (string) - The current status of the request (e.g., "Open", "Completed", "Cancelled"). Note: "Message" type requests do not have a status field.
  - **requestedByUserId** (string) - The ID of the user who created the request.
  - **requestedUserId** (string) - The ID of the user assigned to complete the request.
  - **requestedByUserPosition** (string) - The position of the requesting user within their company (e.g., "CompanyEmployee", "Founder", "OutsourcedAccountantOrCfo").
  - **requestedUserPosition** (string) - The position of the requested user within their company.
  - **requestedByUserFirmGroups** (array of strings) - Firm groups the requesting user belongs to.
  - **requestedUserFirmGroups** (array of strings) - Firm groups the requested user belongs to.
  - **transactionId** (string) - The ID of the transaction associated with the request.
  - **message** (string) - Informational message for the request.
  - **createdAt** (string) - Timestamp when the request was created (ISO 8601 format).
  - **updatedAt** (string) - Timestamp when the request was last updated (ISO 8601 format).

#### Response Example
```json
{
  "requests": [
    {
      "id": "req_5e3bZC1mxNtdwEp8eLg9Y2",
      "type": "CategoryReview",
      "status": "Open",
      "requestedByUserId": "user_1ngwhRvqnZNzoMeVysveLW",
      "requestedUserId": "user_1ngwhRvqnZNzoMeVysveLW",
      "requestedByUserPosition": "Founder",
      "requestedUserPosition": "CompanyEmployee",
      "requestedByUserFirmGroups": ["Payroll team"],
      "requestedUserFirmGroups": ["Payroll team"],
      "transactionId": "txn_5e3bZC1mxNtdwEp8eLg9Y2",
      "message": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}
```
```

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

### Create Financial Account

Source: https://puzzle-api.readme.io/docs/transactions

Creates a new financial account to organize transactions.

```APIDOC
## Create Financial Account

### Description
Creates a new financial account to organize transactions.

### Method
POST

### Endpoint
`/accounts`

### Parameters
#### Request Body
- **name** (string) - Required - The name of the financial account.
- **currency** (string) - Required - The currency of the account (e.g., 'USD').

### Request Example
```json
{
  "name": "Checking Account",
  "currency": "USD"
}
```

### Response
#### Success Response (201 Created)
- **accountId** (string) - The unique identifier for the newly created account.
- **name** (string) - The name of the account.
- **currency** (string) - The currency of the account.

#### Response Example
```json
{
  "accountId": "acc_12345",
  "name": "Checking Account",
  "currency": "USD"
}
```
```

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

### Example Bookkeeping Request Response (JSON)

Source: https://puzzle-api.readme.io/docs/bookkeeping

This JSON structure represents the typical response when retrieving bookkeeping requests via the API. It includes details like request ID, type, status, user information, and associated transaction ID.

```json
{
  "requests": [
    {
      "id": "req_5e3bZC1mxNtdwEp8eLg9Y2",
      "type": "CategoryReview",
      "status": "Open",
      "requestedByUserId": "user_1ngwhRvqnZNzoMeVysveLW",
      "requestedUserId": "user_1ngwhRvqnZNzoMeVysveLW",
      "requestedByUserPosition": "Founder",
      "requestedUserPosition": "CompanyEmployee",
      "requestedByUserFirmGroups": ["Payroll team"],
      "requestedUserFirmGroups": ["Payroll team"],
      "transactionId": "txn_5e3bZC1mxNtdwEp8eLg9Y2"
      "message": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ]
}
```