### Create Payment Term Request Example

Source: https://documentation.tipalti.com/reference/post_api-v1-payment-terms

Use this example to create a new payment term. Ensure you have the necessary 'tipalti.api.payment-term.write' scope.

```json
{
  "externalId": "ExternalId1234",
  "name": "String value",
  "days": 1,
  "isDefault": false
}
```

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

### Example iFrame URL

Source: https://documentation.tipalti.com/docs/iframe-sdk

This is an example of a complete iFrame URL used to load the Tipalti Supplier's Hub. It includes payer, timestamp, and hash key parameters.

```xml
https://3rd.party.com/?payer=tipalti&idap=baseTest&ts=12345678&hashkey=xxsrsdfkjqhwreog325kl

```

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

### Request Body Example for Access Token

Source: https://documentation.tipalti.com/reference/step-1-retrieve-access-token

This example shows the required parameters for requesting an access token. Ensure you replace placeholders with your actual client ID, client secret, and desired scopes.

```text
client_id=XXXXXXXXXXXXXXX
client_secret=YYYYYYYYYYYYYYYY
grant_type=client_credentials
scope=tipalti.api.payee.read%20tipalti.api.payee.write
```

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

### Not Found Example

Source: https://documentation.tipalti.com/reference/get_api-v1-invoice-batches-id

An example response when the requested invoice batch is not found. It includes a trace ID for tracking the request.

```json
{
  "traceId": "ab12c3456d7890123efg4h56ijk789lm"
}
```

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

### Create Payment Batch Request Example

Source: https://documentation.tipalti.com/reference/post_api-v1-payment-batches

This example demonstrates the structure of a request to create a payment batch. A batch can contain up to 5,000 payment instructions. Ensure all required fields for each payment instruction are populated.

```json
{
  "paymentInstructions": [
    {
      "payeeId": "1234555550001234567890000",
      "amountSubmitted": {
        "amount": 11,
        "currency": "USD"
      },
      "refCode": "RefCode1234",
      "scheduledDate": "1970-01-01T00:00:00.000Z",
      "scheduleType": "ARRIVAL",
      "isVisibleToPayeeWhenScheduled": false,
      "isThresholdIgnored": false,
      "isMaxWithholdingApplied": false,
      "isTaxValidationIgnored": false,
      "eWalletMessage": "String value",
      "bankingMessage": "String value",
      "emailMessage": "String value",
      "incomeType": "String value",
      "additionalWithholding": 1.1,
      "usSource": 1.1,
      "payingEntityId": "1234489550001234567891111",
      "customFieldValues": [
        {
          "customFieldId": "1111489550001234567890000",
          "value": "MyCustomFieldValue"
        }
      ]
    }
  ],
  "name": "String value"
}
```

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

### Request Body Example for Token Retrieval

Source: https://documentation.tipalti.com/reference/step-3-retrieve-tokens-1

This example demonstrates the required parameters for the POST request to the token endpoint. Ensure all values, including scopes and redirect URIs, match those used in previous authorization steps.

```text
client_id=XXXXXXXXXXXXXXX
client_secret=YYYYYYYYYYYYYYYY
grant_type=authorization_code
code=ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
scope=tipalti.api.payees.read%20tipalti.api.payees.write%20offline_access
redirect_uri=https://yourdomain.com/redirect_uri
code_verifier=VVVVVVVVVVV
```

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

### Create Invoice Batch Response Example

Source: https://documentation.tipalti.com/reference/post_api-v1-invoice-batches

This example shows a successful response after creating an invoice batch. It includes the unique ID of the batch, its current status, and the time it was created.

```json
{
  "id": "4463092781618608436150000",
  "status": "QUEUED",
  "timeCreated": "2023-10-03T00:00:00.000Z",
  "operationType": "CREATE"
}
```

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

### Deferred Reasons Example

Source: https://documentation.tipalti.com/docs/error

Example of the deferred reasons data type, showing an array of error objects with reason codes and descriptions.

```json
deferred_reasons=[{"reason_code":"10005","reason":"DuplicatePayee"},{"reason_code":"10012","reason":"PendingOFACInfo"}]
```

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

### Create Invoice Batch Request Example

Source: https://documentation.tipalti.com/reference/post_api-v1-invoice-batches

This example demonstrates the structure of a request to create an invoice batch. Batches exceeding 200 invoices or individual invoices with over 100 lines will result in errors. Ensure you have the 'tipalti.api.invoice-batch.write' scope.

```json
{
  "batchHeader": {
    "operationType": "CREATE"
  },
  "items": [
    {
      "batchItemId": "aBc123",
      "refCode": "MyRefCode123",
      "invoiceNumber": "INV_11223344",
      "subject": "Beverages for company meeting",
      "payeeVatNumber": "BE01239954XX",
      "invoiceDate": "2023-01-08T00:00:00Z",
      "dueDate": "2023-01-08T00:00:00Z",
      "currency": "USD",
      "payeeId": "4463092781618608436150000",
      "description": "Food and beverages for the new year toast",
      "payerEntityId": "4463092781618608436150000",
      "apAccountId": "4463092781618608436150000",
      "incomeType": "Patents",
      "customFieldValues": [
        {
          "customFieldId": "5843667032817017815260000",
          "valuesIds": [
            "5843667032817017815260001"
          ],
          "value": null
        }
      ],
      "lines": [
        {
          "description": "Pizza with toppings",
          "quantity": 1,
          "unitPrice": 100.5,
          "netAmount": 100.5,
          "taxAmount": 15.75,
          "taxCodeId": "4463092781618608436150000",
          "expenseAccountId": "415309233111860870001234",
          "customFieldValues": [
            {
              "customFieldId": "5843667032817017815260000",
              "valuesIds": [
                "5843667032817017815260001"
              ],
              "value": null
            }
          ]
        }
      ]
    }
  ]
}
```

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

### Example Redirect URI with Authorization Parameters

Source: https://documentation.tipalti.com/reference/step-2-request-user-authorization

This is an example of the redirect URI that your application will receive after a user authorizes it. It includes a temporary authorization code, the granted scopes, and the state parameter for request verification.

```url
https://[your>> redirect uri]/
?code=4A7AF620B973BF3736F3211980BF899CBF7C7FE9B5BE4B3ABAA535475B75CAEB
&state=WGhEspQLYATiUcAW&scope=tipalti.api.payee.write%20tipalti.api.payee.read%20tipalti.api.payer-entity.read%20offline_access
```

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

### Create Payee Response Example

Source: https://documentation.tipalti.com/reference/post_api-v1-payees

This example shows the structure of a successful response when creating a payee. It includes the payee's ID, status, and other relevant details. The response confirms the creation and provides the unique identifier for the new payee.

```json
{
  "id": "3468489550001234567890000",
  "refCode": "RefCode1234",
  "preferredPayerEntityId": "String value",
  "status": "ACTIVE",
  "statusChangeDateTimeUTC": "1970-01-01T00:00:00.000Z",
  "statusReason": "String value",
  "entityType": "INDIVIDUAL",
  "isAccountClosed": false,
  "isPayable": false,
  "unpayableReasons": [
    "String value"
  ],
  "lastChangeDateTimeUTC": "1970-01-01T00:00:00.000Z",
  "apAccountId": "1234489550001234567891111",
  "paymentTermId": "1234489550001234567891111",
  "contactInformation": {
    "email": "String value",
    "firstName": "James",
    "middleName": "William",
    "lastName": "Smith",
    "companyName": "Tipalti",
    "alias": "String value",
    "address": "1051 E. Hillsdale Boulevard",
    "address2": "Suite 600",
    "city": "Foster City",
    "zip": "94404",
    "stateProvinceCode": "CA",
    "beneficiaryCountryCode": "CA",
    "paymentCountryCode": "US",
    "phone": "5551234",
    "phoneCountryCode": "US",
    "countryOfBirthCode": "US",
    "dateOfBirth": "1970-01-01T00:00:00.000Z"
  }
}
```

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

### Bad Request Example

Source: https://documentation.tipalti.com/reference/get_api-v1-invoice-batches-id

An example of a bad request response, indicating an issue with the provided parameters. Includes an error code, message, and an optional documentation URL.

```json
{
  "errors": [
    {
      "code": "GNRL-123456",
      "message": "Error message",
      "docUrl": "https://documentation.tipalti.com",
      "parameter": "invalidParameterName"
    }
  ],
  "traceId": "ab12c3456d7890123efg4h56ijk789lm"
}
```

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

### Create Payment Batch Success Response Example

Source: https://documentation.tipalti.com/reference/post_api-v1-payment-batches

This example shows a successful response when a payment batch is created. The response includes the unique ID assigned to the newly created batch.

```json
{
  "id": "3468489550001234567890000"
}
```

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

### Create Payee Request Example

Source: https://documentation.tipalti.com/reference/post_api-v1-payees

This example demonstrates the structure of a request body for creating a new payee. It includes custom field values, reference code, entity type, and detailed contact information. Ensure the 'tipalti.api.payee.write' scope is included for this operation.

```json
{
  "customFieldValues": [
    {
      "customFieldId": "1111489550001234567890000",
      "valuesIds": null,
      "value": "MyCustomFieldValue"
    },
    {
      "customFieldId": "2222489550001234567893456",
      "valuesIds": [
        "2222333344441234567890000",
        "2222333344441234567890011"
      ],
      "value": null
    }
  ],
  "refCode": "RefCode1234",
  "preferredPayerEntityId": "String value",
  "entityType": "INDIVIDUAL",
  "contactInformation": {
    "email": "String value",
    "firstName": "James",
    "middleName": "William",
    "lastName": "Smith",
    "companyName": "Tipalti",
    "alias": "String value",
    "address": "1051 E. Hillsdale Boulevard",
    "address2": "Suite 600",
    "city": "Foster City",
    "zip": "94404",
    "stateProvinceCode": "CA",
    "beneficiaryCountryCode": "CA",
    "paymentCountryCode": "US",
    "phone": "5551234",
    "phoneCountryCode": "US",
    "countryOfBirthCode": "US",
    "dateOfBirth": "1970-01-01T00:00:00.000Z",
    "languageCode": "en"
  }
}
```

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

### Response Payload Example for Access Token

Source: https://documentation.tipalti.com/reference/step-1-retrieve-access-token

This is an example of the JSON response received after successfully requesting an access token. The 'access_token' field should be used in subsequent API calls.

```json
{
    "access_token":"AAAAAAAAAAAAAAAAAAAAA",
    "expires_in":3600,
    "token_type":"Bearer",
    "scope":"tipalti.api.payee.read tipalti.api.payee.write"
}
```

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

### Create Custom Field Value Option Response Example (201 Created)

Source: https://documentation.tipalti.com/reference/post_api-v1-custom-fields-id-value-options

This example shows a successful response when a custom field value option is created. It includes the newly generated ID, active status, and the details provided in the request.

```json
{
  "id": "3468489550001234567890000",
  "externalId": "ExternalId1234",
  "isActive": true,
  "payerEntityIds": [
    "1234489550001234567891111",
    "123448955000123456789112"
  ],
  "value": "Value1234"
}
```

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

### Starts With Operator Example

Source: https://documentation.tipalti.com/reference/filtering-1

Filter string fields to check if they begin with a specific substring. Uses the '.startsWith()' method.

```text
Country.startsWith(”US”)
```

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

### Example Failure Email

Source: https://documentation.tipalti.com/docs/retry-policy

This is an example of an email notification sent when a webhook fails after all retry attempts.

```text
Hi,

We failed to send the following webhook: "Payee details changed"
Reason: {"success":false,"error":{"message":"Token \"79c5ea63-d500-4501-93c6-1490e3cfaca0\" not found","id":null}}
Webhook ID(key): WH-11364047031020318935850000-2e6f297a84fd41cf9ff57cc2abba2491
Creation date: 08/08/24 6:47:50 UTC

We recommend reaching out to your system administrator to troubleshoot this issue.

Best regards,
The Tipalti team.
```

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

### Example API Call with Pagination

Source: https://documentation.tipalti.com/reference/pagination-1

Demonstrates how to construct an API request URL with pagination parameters.

```APIDOC
## Example API Call with Pagination

### Description
Shows an example of an API endpoint URL with pagination query parameters.

### Endpoint
`https://api-p.tipalti.com/api/v1/payer-entities?pageSize=10&pageCursor=MQ==`
```

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

### Step 1: Create an authorization request link

Source: https://documentation.tipalti.com/reference/postman-collection-1

This step involves generating a URL to initiate the authorization process. You need to replace placeholders like 'add your client id' and 'add your redirect url' with your actual credentials and callback URL.

```APIDOC
## GET /connect/authorize/callback

### Description
Generates a link to initiate the OAuth 2.0 authorization code flow.

### Method
GET

### Endpoint
https://sso.tipalti.com/connect/authorize/callback

### Query Parameters
- **response_type** (string) - Required - Value should be 'code'
- **state** (string) - Required - A value to maintain state across requests
- **code_challenge** (string) - Required - The code challenge for PKCE
- **code_challenge_method** (string) - Required - The method used for code challenge, typically 'S256'
- **client_id** (string) - Required - Your Tipalti client ID
- **scope** (string) - Required - The scopes you are requesting, e.g., 'offline_access'
- **redirect_uri** (string) - Required - Your registered redirect URI

### Request Example
```
https://sso.tipalti.com/connect/authorize/callback?response_type=code&state=add%20state&code_challenge=add%20code%20challenge&code_challenge_method=S256&client_id=add%20your%20client%20id&scope=add%20your%20scopes%20with%20:%20offline_access&redirect_uri=add%20your%20redirect%20url
```

### Response
#### Success Response (302 Found)
Redirects to the authorization server with the provided parameters.
```

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

### DKIM DNS Record Example

Source: https://documentation.tipalti.com/docs/email-authentication

This is an example of the content for a DKIM TXT record. Ensure the final entry is a single line with no line breaks.

```dns
v=DKIM1;k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDUejllw7R9wJvQ8LoCS5LwXo3xq+ReQWBUMQvktXNmX43LZyDQr0H9dHKuoFsDHwo0nZJk3JAJs610H9dQF+SZyeVL0Pv5Jiq3dSLs/+tyxIBCou20Gy/7b+y6gUvqvMbZWM/fFHfpZgh/3E0vHJXGob/3XxqcW2BtIgxVSf+HTwIDAQAB
```

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

### Example JSON Payload for Webhook Event

Source: https://documentation.tipalti.com/docs/setup

This is an example of a JSON payload for a 'paymentGroupApproved' webhook event. Configure your listener to handle various event data structures.

```json
{
  "id": "WH-9826213830902278428590000-e65e9222359d4a68859f6ff383dd8451",
  "type": "paymentGroupApproved",
  "createdDate": "2024-01-28T08:20:58.546Z",
  "isTest": false,
  "version": "2.0",
  "traceId": "bf2bd97c958ad8e4012ef40617accc2c",
  "eventData": {
    "approvalDate": "2024-02-11T10:11:17.993Z",
    "submissionDate": "2024-02-11T10:11:10.244Z",
    "payments": [
      {
        "paymentStatus": "Submitted",
        "refCode": "123456"
      }
    ]
  }
}
```

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

### API Failed Response Example

Source: https://documentation.tipalti.com/reference/rate-limiting

This is an example of the error body returned when the API rate limit is exceeded. It indicates which limit was reached and provides a template for the message.

```text
{
    Content: 'API calls quota exceeded! The maximum number of requests allowed: X per YYY {s/m/h/d}'
}
```

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

### Get Payment Batch Instructions

Source: https://documentation.tipalti.com/reference/get_api-v1-payment-batches-id-instructions

Fetches the instructions for a given payment batch ID.

```APIDOC
## GET /api/v1/payment-batches/{id}/instructions

### Description
Retrieves the instructions for a specific payment batch.

### Method
GET

### Endpoint
/api/v1/payment-batches/{id}/instructions

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the payment batch.

### Response
#### Success Response (200)
- **instructions** (object) - Contains the payment batch instructions.
  - **instruction_type** (string) - The type of instruction.
  - **instruction_details** (string) - Details of the instruction.

#### Response Example
```json
{
  "instructions": [
    {
      "instruction_type": "ExampleInstructionType",
      "instruction_details": "This is an example instruction detail."
    }
  ]
}
```

#### Error Response (400)
- **ApiErrors** (object) - Contains a list of API errors.
  - **errors** (array) - Array of ApiError objects.
    - **code** (string) - Error identifier.
    - **message** (string) - Informative error message.
    - **docUrl** (string) - Link to documentation.
    - **parameter** (string) - Name of the invalid parameter.
  - **traceId** (string) - Unique identifier of the API request.

#### Error Response Example (400)
```json
{
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "message": "The provided payment batch ID is invalid.",
      "parameter": "id"
    }
  ],
  "traceId": "ab12c3456d7890123efg4h56ijk789lm"
}
```

#### Error Response (404)
- **ApiErrors** (object) - Contains a list of API errors.
  - **errors** (array) - Array of ApiError objects.
    - **code** (string) - Error identifier.
    - **message** (string) - Informative error message.
    - **docUrl** (string) - Link to documentation.
  - **traceId** (string) - Unique identifier of the API request.

#### Error Response Example (404)
```json
{
  "errors": [
    {
      "code": "RESOURCE_NOT_FOUND",
      "message": "Payment batch not found."
    }
  ],
  "traceId": "ab12c3456d7890123efg4h56ijk789lm"
}
```

#### Error Response (429)
- **description**: Too Many Requests

#### Error Response (500)
- **ApiErrorTrace** (object) - Contains trace ID for internal server error.
  - **traceId** (string) - Unique identifier of the API request.

#### Error Response Example (500)
```json
{
  "traceId": "ab12c3456d7890123efg4h56ijk789lm"
}
```
```

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

### Create Payee

Source: https://documentation.tipalti.com/reference/onboard-payees-and-create-payments

Initiates the payee onboarding process by creating a payee profile in Tipalti. The refCode is used to identify the payee in your internal system.

```APIDOC
## POST /api/v1/payees

### Description
Creates a payee profile in Tipalti.

### Method
POST

### Endpoint
/api/v1/payees

### Parameters
#### Request Body
- **refCode** (string) - Required - The reference code that identifies the payee in your internal system.
```

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

### Example iFrame Query String with Token

Source: https://documentation.tipalti.com/docs/faq

Illustrates how to append the 'token' parameter to the iFrame query string before signing it with a dynamic key. The token identifies the dynamic key used for encryption.

```text
payer=my_payer_name&idap=john_doe&token=djowwioasdFDSjkX&hashkey=CCMLSJr037mnkf774kj
```

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

### Authorization Request Link Example (Production)

Source: https://documentation.tipalti.com/reference/step-1-create-an-authorization-request-link

Construct the authorization request link using the production endpoint and required parameters. Ensure all parameters, including scopes and redirect URI, are correctly formatted and URL-encoded.

```url
https://sso.tipalti.com/connect/authorize/callback?response_type=code&state=WGhEspQLYATiUcAW &code_challenge=eBa7OKjAx02p2C3AX2HnWDfU3LDiK4MhipocDuegoUE &code_challenge_method=S256&client_id=XXXXXXXXXXXXXXX &scope=tipalti.api.payee.write%20tipalti.api.payee.read%20tipalti.api.payer-entity.read%20offline_access&redirect_uri=https://yourdomain.com/returnurl
```

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

### Create Custom Field Value Option Request Example

Source: https://documentation.tipalti.com/reference/post_api-v1-custom-fields-id-value-options

This example demonstrates the structure of a request body to create a new value option for a custom field. It includes external ID, value, and associated payer entity IDs.

```json
{
  "externalId": "ExternalId1234",
  "value": "Value1234",
  "payerEntityIds": [
    "1234489550001234567891111",
    "123448955000123456789112"
  ]
}
```

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

### Create Payment Batch

Source: https://documentation.tipalti.com/reference/post_api-v1-payment-batches

The Create payment batch action joins together a list of payments into a single request. A payment batch with more than 5,000 instructions will return an error. Requires the 'tipalti.api.payment-batch.write' scope.

```APIDOC
## POST /api/v1/payment-batches

### Description
Creates a payment batch by joining a list of payments into a single request. Note that batches exceeding 5,000 instructions will result in an error.

### Method
POST

### Endpoint
/api/v1/payment-batches

### Request Body
- **paymentInstructions** (array) - Required - List of payment instructions to be created in the batch.
  - **payeeId** (string) - Required - The ID of the payee.
  - **amountSubmitted** (object) - Required - The submitted amount for the payment.
    - **amount** (number) - Required - The monetary amount.
    - **currency** (string) - Required - The currency of the amount (e.g., USD).
  - **refCode** (string) - Required - A reference code for the payment.
  - **scheduledDate** (string) - Required - The date the payment is scheduled to be processed (ISO 8601 format).
  - **scheduleType** (string) - Required - The type of scheduling (e.g., ARRIVAL).
  - **isVisibleToPayeeWhenScheduled** (boolean) - Optional - Whether the payment is visible to the payee when scheduled.
  - **isThresholdIgnored** (boolean) - Optional - Whether to ignore the threshold.
  - **isMaxWithholdingApplied** (boolean) - Optional - Whether the maximum withholding is applied.
  - **isTaxValidationIgnored** (boolean) - Optional - Whether tax validation is ignored.
  - **eWalletMessage** (string) - Optional - A message for the e-wallet.
  - **bankingMessage** (string) - Optional - A message for banking details.
  - **emailMessage** (string) - Optional - An email message for the payee.
  - **incomeType** (string) - Optional - The type of income.
  - **additionalWithholding** (number) - Optional - Additional withholding amount.
  - **usSource** (number) - Optional - US source information.
  - **payingEntityId** (string) - Optional - The ID of the paying entity.
  - **customFieldValues** (array) - Optional - Custom field values for the payment.
    - **customFieldId** (string) - Required - The ID of the custom field.
    - **value** (string) - Required - The value of the custom field.
- **name** (string) - Optional - The name of the payment batch.

### Request Example
```json
{
  "paymentInstructions": [
    {
      "payeeId": "1234555550001234567890000",
      "amountSubmitted": {
        "amount": 11,
        "currency": "USD"
      },
      "refCode": "RefCode1234",
      "scheduledDate": "1970-01-01T00:00:00.000Z",
      "scheduleType": "ARRIVAL",
      "isVisibleToPayeeWhenScheduled": false,
      "isThresholdIgnored": false,
      "isMaxWithholdingApplied": false,
      "isTaxValidationIgnored": false,
      "eWalletMessage": "String value",
      "bankingMessage": "String value",
      "emailMessage": "String value",
      "incomeType": "String value",
      "additionalWithholding": 1.1,
      "usSource": 1.1,
      "payingEntityId": "1234489550001234567891111",
      "customFieldValues": [
        {
          "customFieldId": "1111489550001234567890000",
          "value": "MyCustomFieldValue"
        }
      ]
    }
  ],
  "name": "String value"
}
```

### Response
#### Success Response (201)
- **id** (string) - The ID of the created payment batch.

#### Response Example
```json
{
  "id": "3468489550001234567890000"
}
```

#### Error Responses
- **400** Bad Request: Invalid request payload or parameters.
- **401** Unauthorized: Authentication failed.
- **403** Forbidden: Insufficient permissions.
- **429** Too Many Requests: Rate limit exceeded.
- **500** Internal Server Error: An unexpected error occurred on the server.
```