{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-Docs/Get-started/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["tabs","tab"]},"type":"markdown"},"seo":{"title":"Overview"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":0},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Get familliar with Talli API fundamentals, including how the API is organised, how authentication works, and how we handle errors, pagination, rate limiting and versioning."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Talli API is built on ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["REST"]}," principles, lets you programmatically manage ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Distributions to beneficiaries"]}," - this includes creating distributions, sending payout instructions, querying balances and bank accounts and pulling reports"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is a machine-to-machine (M2M) API. Your app calls Talli directly over HTTPS with no browser or end-user in the loop."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"conventions","__idx":1},"children":["Conventions"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transport"]},": HTTPS only, Plain HTTP requests are rejected."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Encoding"]},": All requests and responses use 'UTF-8'."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Content type"]},": 'application/json' for request and response bodies, unless an endpoint explicitly accepts or returns another type (e.g. report endponts accept 'text/csv' to stream a CSV file)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Timestamps"]},": ISO 8601 in UTC"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["ID's"]},": Resource identifiers are UUID strings"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Monetary Format"]},": Amounts are returned as decimal numbers in the currency's major unit (e.g '12.50' for USD $12.50), as of this moment, only USD is supported"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"base-url","__idx":2},"children":["Base URL"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Environment"},"children":["Environment"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Base URL"},"children":["Base URL"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Production"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.talli.ai"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Sandbox"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Provided by your Talli representative"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All requests are made against the base URL plus the versioned-prefixed path of the API surface that you're using."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-surfaces","__idx":3},"children":["API surfaces"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Talli exposes a single public API surface for customer-facing integrations:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Surface"},"children":["Surface"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Base path"},"children":["Base path"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Distribution Manager (v3)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/distribution-manager/"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":4},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Talli API uses the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth 2.0 Client Credentials Flow"]}," for authentication. This process involves exchanging your Client ID and Client Secret for a temporary bearer access token. Authentication is identical across all Talli API surfaces"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"credentials","__idx":5},"children":["Credentials"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your Talli representative will provide you with the following:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Credential"},"children":["Credential"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Example (for illustration only)"},"children":["Example (for illustration only)"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Token URL"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The endpoint for requesting access tokens."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://[your-tenant].us.auth0.com/oauth/token"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client ID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Your application's unique public identifier."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["aBcDeFgHiJkLmNoPqRsTuVwXyZ"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Client Secret"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Your application's secret key. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Treat this like a password."]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["123-very-secret-key-456"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Audience"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The unique identifier for the Talli API."]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.talli.ai"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep secrets out of source control. Store them in a dedicated secret management service (e.x. AWS Secrets Manager, Vault, or Google Secret Manager) and inject them into your application at runtime."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"requesting-an-access-token","__idx":6},"children":["Requesting an access token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To get your token, make a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Token URL"]},"."]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"cURL","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl --request POST \\\n  --url https://<your-tenant>.us.auth0.com/oauth/token \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"client_id\": \"YOUR_CLIENT_ID\",\n    \"client_secret\": \"YOUR_CLIENT_SECRET\",\n    \"audience\": \"https://api.talli.ai\",\n    \"grant_type\": \"client_credentials\"\n  }'\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Python","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\n\nresponse = requests.post(\n    \"https://<your-tenant>.us.auth0.com/oauth/token\",\n    json={\n        \"client_id\": \"YOUR_CLIENT_ID\",\n        \"client_secret\": \"YOUR_CLIENT_SECRET\",\n        \"audience\": \"https://api.talli.ai\",\n        \"grant_type\": \"client_credentials\",\n    },\n    timeout=10,\n)\nresponse.raise_for_status()\ntoken = response.json()[\"access_token\"]\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Node","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const response = await fetch(\n  \"https://<your-tenant>.us.auth0.com/oauth/token\",\n  {\n    method: \"POST\",\n    headers: { \"content-type\": \"application/json\" },\n    body: JSON.stringify({\n      client_id: \"YOUR_CLIENT_ID\",\n      client_secret: \"YOUR_CLIENT_SECRET\",\n      audience: \"https://api.talli.ai\",\n      grant_type: \"client_credentials\",\n    }),\n  }\n);\nconst { access_token: token } = await response.json();\n","lang":"javascript"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your credentials are correct, you will receive a JSON response containing your access token."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"access_token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIs...\",\n  \"expires_in\": 36000,\n  \"token_type\": \"Bearer\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important: Handling Your Access Token"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Store it securely:"]}," The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["access_token"]}," is the key to accessing the API. Store it in a secure but temporary location (e.g., in-memory cache)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["It's a Bearer Token:"]}," You will use this token in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header of all subsequent API requests."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["It Expires:"]}," The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expires_in"]}," field indicates the token's lifetime in seconds (e.g., 36000 seconds = 10 hours). Your application should reuse this token until it is close to expiring, at which point you should request a new one. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Please do not request a new token for every API call."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":7},"children":["Error Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Talli API uses standard HTTP response codes to indicate the success or failure of an API request."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP Status code summary"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Request succeeded."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A 'POST' that creates the resource. The response body contains the created resource"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The request was validated and queued for asynchronous processing."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["204 No Content"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A successful write that returns no body, typically a delete or an update without a response payload."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The request is malformed, fails validation, or violates a business rule (e.g. invalid paging, missing required field)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401 Unauthorized"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Your access token is missing, expired, or wasn't issued by Talli. Re-authenticate at the token endpoint."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403 Forbidden"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Token is valid but lacks the permission required for this endpoint."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404 Not Found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The resource does not exist, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["or"]}," it exists but belongs to a different organization."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409 Conflict"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Request conflicts with the resource's current state (e.g. payout instruction cannot transition from its current state)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429 Too Many Requests"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Rate limit exceeded - see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#15-rate-limits"},"children":["Rate Limits"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500 Internal Server Error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Something went wrong on our side. The response body includes a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]}," - share it with support and we can trace the request."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ","Error responses are returned as ProblemDetails objects, the format defined by ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc7807"},"children":["RFC 7807"]},". Every error body includes type, title, status, and detail. 5xx responses also include a requestId, which you can send over to support."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"type\": \"Not Found\",\n    \"title\": \"An error occurred while processing your request.\",\n    \"status\": 404,\n    \"detail\": \"Payout instruction with id 1a2b3c4d-e5f6-7890-1234-567890abcdef was not found\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Stable identifier for the error class - a short label such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Not Found"]}," on a validated request, or an RFC 9110 section link such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://tools.ietf.org/html/rfc9110#section-15.6.1"]}," on an unexpected error."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Short, human-readable summary."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["HTTP status code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["detail"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Readable explanation of ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["this"]}," occurrence."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errorCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Stable, machine-readable code for the error class, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["INTERNAL_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BAD_REQUEST"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYLOAD_TOO_LARGE"]},". Present on unexpected errors; prefer it over ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," when branching in code."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Correlates to a single request in Talli's logs. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Include in support tickets."]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["traceId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Distributed-trace identifier across our services."]}]}]}]}]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}," never carries the underlying error text - the body is always the fixed shape below, and the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestId"]}," is what lets support find the failing request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"type\": \"https://tools.ietf.org/html/rfc9110#section-15.6.1\",\n    \"title\": \"An error occurred\",\n    \"status\": 500,\n    \"detail\": \"An unexpected error occurred. Quote requestId when contacting Talli support.\",\n    \"errorCode\": \"INTERNAL_ERROR\",\n    \"requestId\": \"0HN7Q9V2D2L0J:00000004\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Validation errors"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For 400 validation failures from invalid request bodies/query strings, the response follows RFC 7807's validation extension and includes per-field error messages under errors:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n\"type\": \"https://tools.ietf.org/html/rfc9110#section-15.5.1\",\n\"title\": \"One or more validation errors occurred.\",\n\"status\": 400,\n\"errors\": {\n    \"bankAccountId\": [\n    \"Bank account is still Pending — wait for activation before promoting the draft.\"\n    ],\n    \"description\": [\n    \"The 'description' field must not exceed 512 characters.\"\n    ]\n},\n\"requestId\": \"0HN7Q9V2D2L0J:00000004\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reporting errors to support"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Capture and include the requestId (and traceId when present) when contacting support@talli.ai, it lets us jump directly to the failing request in our logs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pagination","__idx":8},"children":["Pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Talli API list methods let you retrieve collections of resources, e.g. such as listing distributions, payout instructions or bank accounts. These methods share a common structure, taking at least 'pageNumber' and 'pageSize' as query parameters."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"request-parameters","__idx":9},"children":["Request parameters"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Default"},"children":["Default"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["1-indexed page to return."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["20"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Items per page. Max varies by endpoint (commonly ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["100"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1000"]}," for report exports)."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"  curl --request GET \\\n    --url 'https://api.talli.ai/v3/distribution-manager/distributions?pageNumber=1&pageSize=20' \\\n    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both parameters are typically required, meaning callers should always specify them."," ","Some list methods additionally accept sortBy and sortDirection (Asc | Desc); valid sortBy values are per-endpoint enums documented in the API Reference."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-structure","__idx":10},"children":["Response structure"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Derived from the request."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pageSize"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Derived from the request."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalPages"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Total pages available for the current filter set."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totalItems"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Total items across all pages."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The page contents, an array of the resource type for that endpoint."]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"pageNumber\": 1,\n    \"pageSize\": 20,\n    \"totalPages\": 5,\n    \"totalItems\": 87,\n    \"data\": [\n      {\n        \"id\": \"1a2b3c4d-e5f6-7890-1234-567890abcdef\",\n        \"name\": \"Q2 Field Marketing Distribution\",\n        \"businessEntity\": \"Talli\"\n      }\n    ]\n  }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"rate-limits","__idx":11},"children":["Rate Limits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Talli API enforces rate limits to protect the platform from accidental overload and abuse. Limits are applied ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["per organization"]},", so other customer's traffic never affects your budget. Rate limits are scoped ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["per endpoint group"]}," — different endpoints can have different limits."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"reading-your-usage","__idx":12},"children":["Reading your usage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every response from a rate-limited endpoint includes these headers, so you can monitor your usage proactively without waiting to be throttled:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-RateLimit-Limit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The maximum number of requests allowed in the current window for this endpoint."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-RateLimit-Remaining"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The number of requests still available in the current window."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-RateLimit-Reset"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The time the window resets, as a Unix timestamp (seconds since the epoch, UTC)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We recommend reading ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-RateLimit-Remaining"]}," and backing off as it approaches ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]},", rather than waiting for a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]},"."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The exact limit for any endpoint is always reported in its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-RateLimit-Limit"]}," header — treat that"," ","header as the source of truth rather than hard-coding the values above, as limits may be tuned over time."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exceeding-the-limit","__idx":13},"children":["Exceeding the limit"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you exceed a limit, the API responds with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429 Too Many Requests"]}]},". The response includes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Retry-After"]}]}," header - the number of seconds to wait before retrying."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-RateLimit-"]}," headers (with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-RateLimit-Remaining: 0"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.rfc-editor.org/rfc/rfc9457"},"children":["Problem Details"]}," body, consistent with the API's other error responses:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"type\": \"https://tools.ietf.org/html/rfc6585#section-4\",\n  \"title\": \"Too Many Requests\",\n  \"status\": 429,\n  \"detail\": \"Rate limit exceeded. Please retry later.\",\n  \"instance\": \"POST /v3/distribution-manager/payout-instructions/{id}/:initiate\",\n  \"requestId\": \"0HN…\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"endpoint-limits","__idx":14},"children":["Endpoint limits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The table below lists the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["current"]}," limits. All limits are per organization and use a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sliding"," ","window"]}," (e.g. \"60 / minute\" means no more than 60 requests in any rolling 60-second period). In the"," ","routes below, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["…"]}," stands for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v3/distribution-manager"]}," Url prefix."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Endpoint(s)"},"children":["Endpoint(s)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Limit"},"children":["Limit"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Default"]}," — every public API endpoint not listed below"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["60 / minute"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST …/payout-instructions/{id}/:initiate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["20 / minute"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST …/payout-instructions/{id}/:reinitiate"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["20 / minute"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST …/payout-instructions/{id}/:send-reminder"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["20 / minute"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST …/templates/:send-preview"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["50 / day"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Singular live-send endpoints"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":initiate"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":reinitiate"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":send-reminder"]},") carry the tighter"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["20 / minute"]}," limit because each call triggers an outbound email to a beneficiary. The"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["templates/:send-preview"]}," endpoint, which sends a live test email, is capped at ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["50 / day"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For high-volume distribution, use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["bulk"]}," endpoints (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["…/payout-instructions/:initiate"]}," and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["…/:send-reminders"]}," at the distribution level) rather than scripting many singular calls."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"versioning","__idx":15},"children":["Versioning"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Talli versions the API in the URL path segment. Versions are major-version-only, meaning there are no minor versions like v3.1."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Currently"]}," supported versions:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Version"},"children":["Version"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Surface"},"children":["Surface"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Status"},"children":["Status"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v3"]}]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Distribution Manager"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Current"]}," and recommended."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"backwards-compatible-changes","__idx":16},"children":["Backwards-compatible changes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We may make the following changes within a major version without advance notice:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Adding new endpoints."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Adding new optional request fields."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Adding new fields to response bodies."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Adding new enum values."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Adding new HTTP headers."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Adding new optional query parameters."]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tip: Build your integration to ignore fields it does not recognize."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"breaking-changes","__idx":17},"children":["Breaking changes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Breaking changes require a new major version. We treat the following as ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["breaking"]},":"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Removing or renaming an endpoint, field, or enum value."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Changing the type of an existing field."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Changing authentication or authorization requirements."]}]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can check most recent changes done to the API in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/changelog/changelog"},"children":["Changelog"]}]}]}]},"headings":[{"value":"Overview","id":"overview","depth":2},{"value":"Conventions","id":"conventions","depth":3},{"value":"Base URL","id":"base-url","depth":3},{"value":"API surfaces","id":"api-surfaces","depth":3},{"value":"Authentication","id":"authentication","depth":2},{"value":"Credentials","id":"credentials","depth":3},{"value":"Requesting an access token","id":"requesting-an-access-token","depth":3},{"value":"Error Handling","id":"error-handling","depth":2},{"value":"Pagination","id":"pagination","depth":2},{"value":"Request parameters","id":"request-parameters","depth":3},{"value":"Response structure","id":"response-structure","depth":3},{"value":"Rate Limits","id":"rate-limits","depth":2},{"value":"Reading your usage","id":"reading-your-usage","depth":3},{"value":"Exceeding the limit","id":"exceeding-the-limit","depth":3},{"value":"Endpoint limits","id":"endpoint-limits","depth":3},{"value":"Versioning","id":"versioning","depth":2},{"value":"Backwards-compatible changes","id":"backwards-compatible-changes","depth":3},{"value":"Breaking changes","id":"breaking-changes","depth":3}],"frontmatter":{"seo":{"title":"Overview"}},"lastModified":"2026-09-15T10:50:41.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/get-started/api-basics","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}