{ "openapi": "3.0.4", "info": { "title": "Nova API", "version": "1.24.0", "contact": { "name": "Nova Engineering", "email": "support@nova.net" }, "description": "The Nova API exposes programmatic access to fund operations including distributions, vehicles, entities, contacts, and financial accounts. Authentication is via OAuth2 client_credentials with per-scope authorization. Requests identify the acting organization with the `X-Organization-Id` header, which is optional when the access token is bound to an organization or the integration has access to exactly one." }, "servers": [ { "url": "https://api.nova.net" }, { "url": "https://api.nova-sandbox.net" } ], "security": [ { "OAuth2": [] } ], "tags": [ { "name": "Authentication", "description": "OAuth2 client_credentials token exchange" }, { "name": "Distributions", "description": "Manage distributions" }, { "name": "Entities", "description": "Manage entities" }, { "name": "Payment Instructions", "description": "Manage payment instructions for entities" }, { "name": "Contacts", "description": "Manage contacts" }, { "name": "Organizations", "description": "Read organizations" }, { "name": "Vehicles", "description": "Read vehicles" }, { "name": "Financial Accounts", "description": "Read a vehicle's financial accounts and balances" } ], "components": { "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "OAuth2 client_credentials grant for server-to-server access. Onboard via your Nova admin to receive a `client_id` and `client_secret`, then `POST /oauth/token` to exchange them for a short-lived access token. Send the token as `Authorization: Bearer ` on every authenticated request. Tokens expire after 3600 seconds — refresh by re-exchanging credentials.", "flows": { "clientCredentials": { "tokenUrl": "/oauth/token", "scopes": { "organizations:read": "Read organization data", "organizations:write": "Create or update organization data", "organizations:*": "Full access to organization data", "distributions:read": "Read distribution data", "distributions:write": "Create or update distributions", "distributions:*": "Full access to distributions", "vehicles:read": "Read vehicle data", "vehicles:write": "Create or update vehicles", "vehicles:*": "Full access to vehicles", "entities:read": "Read entity data", "entities:write": "Create or update entities", "entities:*": "Full access to entities", "contacts:read": "Read contact data", "contacts:write": "Create or update contacts", "contacts:*": "Full access to contacts", "financial_accounts:read": "Read financial account data", "financial_accounts:write": "Create or update financial accounts", "financial_accounts:*": "Full access to financial accounts" } } } } }, "schemas": { "DateOrDateTime": { "type": "string", "format": "date-time", "example": "2026-09-09T09:00:00-07:00", "x-mint": { "post": [ "DateOrDateTime" ] }, "description": "Type: [`DateOrDateTime`](/types/date-or-date-time) _ISO 8601 Date or Date and time_" }, "ZonedDateTime": { "type": "string", "format": "date-time", "example": "2026-09-09T09:00:00", "x-mint": { "post": [ "ZonedDateTime" ] }, "description": "Type: [`ZonedDateTime`](/types/zoned-date-time) _ISO 8601 Date and time in the record's [`TimeZone`](/types/time-zone)_" }, "UtcDateTime": { "type": "string", "format": "date-time", "example": "2026-01-01T09:00:00.000Z", "x-mint": { "post": [ "UtcDateTime" ] }, "description": "Type: [`UtcDateTime`](/types/utc-date-time) _Date and time in UTC_" }, "TimeZone": { "type": "string", "default": "UTC", "example": "America/Los_Angeles", "externalDocs": { "url": "https://en.wikipedia.org/wiki/List_of_tz_database_time_zones", "description": "IANA timezone names" }, "x-mint": { "post": [ "TimeZone" ] }, "description": "Type: [`TimeZone`](/types/time-zone) _IANA timezone name_" }, "Error": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "error" ], "description": "Object type identifier.", "example": "error" }, "type": { "$ref": "#/components/schemas/ApiErrorType" }, "code": { "$ref": "#/components/schemas/ApiErrorCode" }, "message": { "type": "string", "description": "Human-readable error message intended for developers, not end-users." }, "status": { "type": "integer", "description": "HTTP status code.", "example": 404 }, "doc_url": { "type": "string", "format": "uri", "description": "Link to the documentation page for this error `code`.", "example": "https://docs.nova.net/errors/parameter_invalid_integer" }, "request_id": { "type": "string", "description": "Request identifier for support inquiries." }, "invalid-params": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/ApiErrorCode" }, "name": { "type": "string", "description": "The request parameter that caused the error." }, "reason": { "type": "string", "description": "Human-readable explanation of why the parameter is invalid." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "nullable": true } ], "description": "The value of the request parameter that caused the error, if applicable." }, "conflicts_with": { "type": "string", "description": "For conflict errors, the id of the existing resource this parameter conflicts with." } }, "required": [ "code", "name", "reason" ] }, "description": "The request parameters that caused the error, if applicable." } }, "required": [ "object", "type", "code", "message", "status" ], "example": { "object": "error", "type": "invalid_request_error", "code": "parameter_invalid_integer", "message": "One or more fields failed validation.", "status": 400, "doc_url": "https://docs.nova.net/errors/parameter_invalid_integer", "invalid-params": [ { "code": "parameter_invalid_integer", "name": "query.limit", "value": 200, "reason": "Too big: expected number to be <=100" } ] } }, "ApiErrorType": { "type": "string", "enum": [ "authentication_error", "permission_error", "invalid_request_error", "not_found_error", "request_timeout_error", "conflict_error", "unprocessable_entity_error", "rate_limit_error", "api_error" ], "description": "Machine-readable high-level error category." }, "ApiErrorCode": { "oneOf": [ { "type": "string", "enum": [ "unauthorized", "forbidden", "resource_not_found", "request_timeout", "conflict", "idempotency_mismatch", "rate_limit_exceeded", "internal_error", "not_implemented", "bad_gateway" ] }, { "$ref": "#/components/schemas/ValidationCode" } ], "description": "Machine-readable high-level error code." }, "ValidationCode": { "type": "string", "enum": [ "parameter_missing", "parameter_unknown", "parameter_invalid", "parameter_invalid_string", "parameter_invalid_string_empty", "parameter_invalid_integer", "validation_error" ], "description": "Machine-readable validation error code." }, "ContactRef": { "type": "object", "properties": { "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^cnt_[A-Za-z0-9]+$", "description": "ID of the contact", "example": "cnt_tSfCZrNE8O3c4QATSkzuCljMZ2DI" } }, "required": [ "id" ], "additionalProperties": false }, "EntityRef": { "type": "object", "properties": { "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^ent_[A-Za-z0-9]+$", "description": "ID of the entity", "example": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p" } }, "required": [ "id" ], "additionalProperties": false }, "DistributionRef": { "type": "object", "properties": { "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^dst_[A-Za-z0-9]+$", "description": "ID of the distribution", "example": "dst_tQaOR74NP2DZ9mg3votpOnCqAuGs" } }, "required": [ "id" ], "additionalProperties": false }, "OrganizationId": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^org_[A-Za-z0-9]+$", "description": "ID of the organization the request acts on. Optional when the access token is bound to a specific `organization`, or when the integration has access to exactly one organization.", "example": "org_EkzhrUc3U6C0UbxNBlK7WLz51ofT" }, "IdempotencyKey": { "type": "string", "description": "Only applies to POST, PUT, PATCH, and DELETE; ignored on reads.\n\nType: [`IdempotencyKey`](/types/idempotency-key) _A unique key that makes a mutating request safely retryable, kept for 24 hours_" }, "DistributionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier.", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Distribution" }, "description": "The page of items." }, "next_page_url": { "type": "string", "nullable": true, "description": "URL for the next page of the list, or `null` when there are no more pages.", "example": "/v1/distributions?page=page_5dr8SFDbv7rZ2aj4&limit=10" }, "previous_page_url": { "type": "string", "nullable": true, "description": "URL for the previous page of the list, or `null` when there are none.", "example": "/v1/distributions?page_before=page_8VtqLBv3xJpY7mk2&limit=10" }, "has_more": { "type": "boolean", "description": "Whether there are more items available after this page. Deprecated: `next_page_url` is non-null exactly when more pages exist.", "deprecated": true }, "url": { "type": "string", "description": "Path identifying this list. Deprecated: on lists embedded in another object, or returned by a create, it may not be a GET endpoint you can call. Follow `next_page_url` / `previous_page_url` to paginate.", "example": "/v1/distributions", "deprecated": true } }, "required": [ "object", "data", "next_page_url", "previous_page_url", "has_more", "url" ], "additionalProperties": false, "x-mint": { "post": [ "List" ] }, "description": "Type: [`List`](/types/list) _A page of results_" }, "Distribution": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "distribution" ], "description": "Object type identifier.", "example": "distribution" }, "livemode": { "type": "boolean", "description": "Whether this object exists in live mode (`true`) or test mode (`false`)." }, "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^dst_[A-Za-z0-9]+$", "description": "ID of the distribution", "example": "dst_tQaOR74NP2DZ9mg3votpOnCqAuGs" }, "name": { "type": "string", "minLength": 1, "example": "November 9th Distribution from XYZ Sale" }, "vehicle": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^veh_[A-Za-z0-9]+$", "description": "ID of the vehicle this distribution pays from", "example": "veh_pNvehE6O1KjY2W6Omq9MD3QAEs5w" }, "external_reference": { "type": "string", "nullable": true, "description": "Your own identifier for this distribution", "example": "distribution-123" }, "distribution_date": { "allOf": [ { "$ref": "#/components/schemas/ZonedDateTime" }, { "example": "2026-09-09T09:00:00-07:00", "description": "The date this distribution pays out, in `distribution_timezone`.\n\nType: [`ZonedDateTime`](/types/zoned-date-time) _ISO 8601 Date and time in the record's [`TimeZone`](/types/time-zone)_" } ] }, "distribution_timezone": { "allOf": [ { "$ref": "#/components/schemas/TimeZone" }, { "description": "The timezone `distribution_date` and every `payments[].distribution_date_override` are interpreted in, and rendered with in responses.\n\nType: [`TimeZone`](/types/time-zone) _IANA timezone name_" } ] }, "short_id": { "type": "string" }, "status": { "$ref": "#/components/schemas/DistributionStatus" }, "published_at": { "allOf": [ { "$ref": "#/components/schemas/UtcDateTime" }, { "nullable": true } ] }, "approved_at": { "allOf": [ { "$ref": "#/components/schemas/UtcDateTime" }, { "nullable": true } ] }, "executed_at": { "allOf": [ { "$ref": "#/components/schemas/UtcDateTime" }, { "nullable": true } ] }, "cancelled_at": { "allOf": [ { "$ref": "#/components/schemas/UtcDateTime" }, { "nullable": true } ] }, "created_at": { "$ref": "#/components/schemas/UtcDateTime" }, "updated_at": { "$ref": "#/components/schemas/UtcDateTime" }, "sender_url": { "type": "string", "format": "uri", "description": "A link for the sender to manage this distribution in the Nova dashboard.", "example": "https://nova.angellist.com/path_to_sender_distribution" }, "recipient_url": { "type": "string", "format": "uri", "description": "A link for any recipient to view this distribution in the Nova dashboard.", "example": "https://nova.angellist.com/path_to_recipient_distribution" }, "payments": { "$ref": "#/components/schemas/DistributionPaymentList" } }, "required": [ "object", "livemode", "id", "name", "vehicle", "external_reference", "distribution_date", "distribution_timezone", "short_id", "status", "published_at", "approved_at", "executed_at", "cancelled_at", "created_at", "updated_at", "sender_url", "recipient_url", "payments" ], "additionalProperties": false }, "DistributionStatus": { "type": "string", "enum": [ "draft", "published", "approved", "executed", "cancelled" ], "example": "published", "x-mint": { "post": [ "DistributionStatus" ] }, "description": "Type: [`DistributionStatus`](/types/distribution#status) _Where the distribution is in its lifecycle_" }, "DistributionPaymentList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier.", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DistributionPayment" }, "description": "The page of items." }, "next_page_url": { "type": "string", "nullable": true, "description": "URL for the next page of the list, or `null` when there are no more pages.", "example": "/v1/distributions/dst_tQaOR74NP2DZ9mg3votpOnCqAuGs/payments?page=page_5dr8SFDbv7rZ2aj4&limit=10" }, "previous_page_url": { "type": "string", "nullable": true, "description": "URL for the previous page of the list, or `null` when there are none.", "example": "/v1/distributions/dst_tQaOR74NP2DZ9mg3votpOnCqAuGs/payments?page_before=page_8VtqLBv3xJpY7mk2&limit=10" }, "has_more": { "type": "boolean", "description": "Whether there are more items available after this page. Deprecated: `next_page_url` is non-null exactly when more pages exist.", "deprecated": true }, "url": { "type": "string", "description": "Path identifying this list. Deprecated: on lists embedded in another object, or returned by a create, it may not be a GET endpoint you can call. Follow `next_page_url` / `previous_page_url` to paginate.", "example": "/v1/distributions/dst_tQaOR74NP2DZ9mg3votpOnCqAuGs/payments", "deprecated": true } }, "required": [ "object", "data", "next_page_url", "previous_page_url", "has_more", "url" ], "additionalProperties": false, "x-mint": { "post": [ "List" ] }, "description": "Type: [`List`](/types/list) _A page of results_" }, "DistributionPayment": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "distribution_payment" ], "description": "Object type identifier.", "example": "distribution_payment" }, "livemode": { "type": "boolean", "description": "Whether this object exists in live mode (`true`) or test mode (`false`)." }, "id": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^dpmt_[A-Za-z0-9]+$", "description": "ID of the distribution payment", "example": "dpmt_sSTfFdsytyOearj36zDNcmXn1pJ4" }, "amount": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Amount in the smallest currency unit", "example": 1000 }, "currency": { "$ref": "#/components/schemas/Currency" }, "distribution_date_override": { "allOf": [ { "$ref": "#/components/schemas/ZonedDateTime" }, { "nullable": true, "example": "2026-09-16T09:00:00-07:00", "description": "The date this payment pays out, in the distribution's `distribution_timezone`. Null if no override was specified, in which case the payment pays out on the distribution's `distribution_date`.\n\nType: [`ZonedDateTime`](/types/zoned-date-time) _ISO 8601 Date and time in the record's [`TimeZone`](/types/time-zone)_" } ] }, "status": { "$ref": "#/components/schemas/DistributionPaymentStatus" }, "recipient_confirmed_at": { "allOf": [ { "$ref": "#/components/schemas/UtcDateTime" }, { "nullable": true } ] }, "verified_at": { "allOf": [ { "$ref": "#/components/schemas/UtcDateTime" }, { "nullable": true } ] }, "entity": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^ent_[A-Za-z0-9]+$", "description": "ID of the entity", "example": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p" }, "payment_instructions": { "type": "string", "nullable": true, "minLength": 32, "maxLength": 32, "pattern": "^pmi_[A-Za-z0-9]+$", "description": "ID of the payment instructions", "example": "pmi_021wlGURMlk80cYuKBjENXqwC3OV" }, "notifications": { "$ref": "#/components/schemas/DistributionNotificationList" } }, "required": [ "object", "livemode", "id", "amount", "currency", "distribution_date_override", "status", "recipient_confirmed_at", "verified_at", "entity", "payment_instructions", "notifications" ], "additionalProperties": false }, "Currency": { "type": "string", "enum": [ "USD" ], "example": "USD", "x-mint": { "post": [ "Currency" ] }, "description": "Type: [`Currency`](/types/currency) _ISO 4217 currency code (USD-only currently)_" }, "DistributionPaymentStatus": { "type": "string", "enum": [ "staged", "recipient_confirmed", "verified", "disbursed", "failed", "returned" ], "example": "staged", "x-mint": { "post": [ "DistributionPaymentStatus" ] }, "description": "Type: [`DistributionPaymentStatus`](/types/distribution-payment#status) _Where the payment is in its lifecycle_" }, "DistributionNotificationList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier.", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DistributionNotification" }, "description": "The page of items." }, "next_page_url": { "type": "string", "nullable": true, "description": "URL for the next page of the list, or `null` when there are no more pages.", "example": "/v1/distribution_payments/dpmt_sSTfFdsytyOearj36zDNcmXn1pJ4/notifications?page=page_5dr8SFDbv7rZ2aj4&limit=10" }, "previous_page_url": { "type": "string", "nullable": true, "description": "URL for the previous page of the list, or `null` when there are none.", "example": "/v1/distribution_payments/dpmt_sSTfFdsytyOearj36zDNcmXn1pJ4/notifications?page_before=page_8VtqLBv3xJpY7mk2&limit=10" }, "has_more": { "type": "boolean", "description": "Whether there are more items available after this page. Deprecated: `next_page_url` is non-null exactly when more pages exist.", "deprecated": true }, "url": { "type": "string", "description": "Path identifying this list. Deprecated: on lists embedded in another object, or returned by a create, it may not be a GET endpoint you can call. Follow `next_page_url` / `previous_page_url` to paginate.", "example": "/v1/distribution_payments/dpmt_sSTfFdsytyOearj36zDNcmXn1pJ4/notifications", "deprecated": true } }, "required": [ "object", "data", "next_page_url", "previous_page_url", "has_more", "url" ], "additionalProperties": false, "x-mint": { "post": [ "List" ] }, "description": "Type: [`List`](/types/list) _A page of results_" }, "DistributionNotification": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "distribution_notification" ], "description": "Object type identifier.", "example": "distribution_notification" }, "livemode": { "type": "boolean", "description": "Whether this object exists in live mode (`true`) or test mode (`false`)." }, "id": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^dntf_[A-Za-z0-9]+$", "description": "ID of the distribution notification", "example": "dntf_bXlZNOmqHkAM8gS4h12vtwlI9sJx" }, "contact": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^cnt_[A-Za-z0-9]+$", "description": "Contact associated with this payment.", "example": "cnt_tSfCZrNE8O3c4QATSkzuCljMZ2DI" } }, "required": [ "object", "livemode", "id", "contact" ], "additionalProperties": false }, "DistributionCreateInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "example": "November 9th Distribution from XYZ Sale" }, "vehicle": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^veh_[A-Za-z0-9]+$", "description": "ID of the vehicle this distribution pays from", "example": "veh_pNvehE6O1KjY2W6Omq9MD3QAEs5w" }, "external_reference": { "type": "string", "nullable": true, "description": "Your own identifier for this distribution", "example": "distribution-123" }, "distribution_date": { "allOf": [ { "$ref": "#/components/schemas/ZonedDateTime" }, { "example": "2026-09-09T09:00", "description": "The date this distribution pays out, in `distribution_timezone`.\n\n**NOTE**: An offset that does not match the zone on this date is rejected\n\nType: [`ZonedDateTime`](/types/zoned-date-time) _ISO 8601 Date and time in the record's [`TimeZone`](/types/time-zone)_" } ] }, "distribution_timezone": { "type": "string", "nullable": true, "default": "UTC", "example": "America/Los_Angeles", "externalDocs": { "url": "https://en.wikipedia.org/wiki/List_of_tz_database_time_zones", "description": "IANA timezone names" }, "x-mint": { "post": [ "TimeZone" ] }, "description": "The timezone `distribution_date` and every `payments[].distribution_date_override` are interpreted in, and rendered with in responses.\n\nType: [`TimeZone`](/types/time-zone) _IANA timezone name_" }, "payments": { "type": "array", "items": { "$ref": "#/components/schemas/DistributionPaymentInput" }, "minItems": 1, "description": "List of payments" } }, "required": [ "name", "vehicle", "distribution_date", "payments" ], "additionalProperties": false }, "DistributionPaymentInput": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 0, "exclusiveMinimum": true, "description": "Amount in the smallest currency unit", "example": 1000 }, "currency": { "$ref": "#/components/schemas/Currency" }, "distribution_date_override": { "type": "string", "nullable": true, "format": "date-time", "example": "2026-09-16T09:00", "x-mint": { "post": [ "ZonedDateTime" ] }, "description": "The date this payment pays out, in the distribution's `distribution_timezone`. Omit to use the distribution's `distribution_date`.\n\nType: [`ZonedDateTime`](/types/zoned-date-time) _ISO 8601 Date and time in the record's [`TimeZone`](/types/time-zone)_" }, "entity": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^ent_[A-Za-z0-9]+$", "description": "ID of the entity receiving this payment. The entity will have an implicit association created with the distribution vehicle.", "example": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p" }, "notifications": { "type": "array", "items": { "$ref": "#/components/schemas/DistributionNotificationInput" }, "description": "Contacts to associate with this payment on publish (no emails sent — notification records only). Each is also implicitly associated with the payment’s entity." } }, "required": [ "amount", "currency", "entity", "notifications" ], "additionalProperties": false }, "DistributionNotificationInput": { "type": "object", "properties": { "contact": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^cnt_[A-Za-z0-9]+$", "description": "ID of the contact", "example": "cnt_tSfCZrNE8O3c4QATSkzuCljMZ2DI" } }, "required": [ "contact" ], "additionalProperties": false }, "EntityPaymentInstructionsList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier.", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityPaymentInstructions" }, "description": "The page of items." }, "next_page_url": { "type": "string", "nullable": true, "description": "URL for the next page of the list, or `null` when there are no more pages.", "example": "/v1/entities/ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p/payment_instructions?page=page_5dr8SFDbv7rZ2aj4&limit=10" }, "previous_page_url": { "type": "string", "nullable": true, "description": "URL for the previous page of the list, or `null` when there are none.", "example": "/v1/entities/ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p/payment_instructions?page_before=page_8VtqLBv3xJpY7mk2&limit=10" }, "has_more": { "type": "boolean", "description": "Whether there are more items available after this page. Deprecated: `next_page_url` is non-null exactly when more pages exist.", "deprecated": true }, "url": { "type": "string", "description": "Path identifying this list. Deprecated: on lists embedded in another object, or returned by a create, it may not be a GET endpoint you can call. Follow `next_page_url` / `previous_page_url` to paginate.", "example": "/v1/entities/ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p/payment_instructions", "deprecated": true } }, "required": [ "object", "data", "next_page_url", "previous_page_url", "has_more", "url" ], "additionalProperties": false, "x-mint": { "post": [ "List" ] }, "description": "Type: [`List`](/types/list) _A page of results_" }, "EntityPaymentInstructions": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "entity_payment_instructions" ], "description": "Object type identifier.", "example": "entity_payment_instructions" }, "livemode": { "type": "boolean", "description": "Whether this object exists in live mode (`true`) or test mode (`false`)." }, "entity": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^ent_[A-Za-z0-9]+$", "description": "ID of the entity", "example": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p" }, "payment_instructions": { "$ref": "#/components/schemas/PaymentInstructionsList" } }, "required": [ "object", "livemode", "entity", "payment_instructions" ], "additionalProperties": false }, "PaymentInstructionsList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier.", "example": "list" }, "data": { "type": "array", "items": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^pmi_[A-Za-z0-9]+$", "description": "ID of the payment instructions", "example": "pmi_021wlGURMlk80cYuKBjENXqwC3OV" }, "description": "The page of items." }, "next_page_url": { "type": "string", "nullable": true, "description": "URL for the next page of the list, or `null` when there are no more pages.", "example": "/v1/entities/ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p/payment_instructions?page=page_5dr8SFDbv7rZ2aj4&limit=10" }, "previous_page_url": { "type": "string", "nullable": true, "description": "URL for the previous page of the list, or `null` when there are none.", "example": "/v1/entities/ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p/payment_instructions?page_before=page_8VtqLBv3xJpY7mk2&limit=10" }, "has_more": { "type": "boolean", "description": "Whether there are more items available after this page. Deprecated: `next_page_url` is non-null exactly when more pages exist.", "deprecated": true }, "url": { "type": "string", "description": "Path identifying this list. Deprecated: on lists embedded in another object, or returned by a create, it may not be a GET endpoint you can call. Follow `next_page_url` / `previous_page_url` to paginate.", "example": "/v1/entities/ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p/payment_instructions", "deprecated": true } }, "required": [ "object", "data", "next_page_url", "previous_page_url", "has_more", "url" ], "additionalProperties": false, "x-mint": { "post": [ "List" ] }, "description": "Type: [`List`](/types/list) _A page of results_" }, "EntityPaymentInstructionsInput": { "type": "object", "properties": { "entity": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^ent_[A-Za-z0-9]+$", "description": "ID of the entity", "example": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p" }, "payment_instructions": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentInstructionsCreateInput" }, "minItems": 1 } }, "required": [ "entity", "payment_instructions" ], "additionalProperties": false }, "PaymentInstructionsCreateInput": { "oneOf": [ { "$ref": "#/components/schemas/AchInstructionsInput" }, { "$ref": "#/components/schemas/DomesticWireInstructionsInput" }, { "$ref": "#/components/schemas/InternationalWireInstructionsInput" } ], "discriminator": { "propertyName": "type", "mapping": { "ach": "#/components/schemas/AchInstructionsInput", "domestic_wire": "#/components/schemas/DomesticWireInstructionsInput", "international_wire": "#/components/schemas/InternationalWireInstructionsInput" } } }, "AchInstructionsInput": { "type": "object", "properties": { "beneficiary_name": { "type": "string", "description": "Name of the account holder, as registered with the bank.", "example": "Jane Doe" }, "account_number": { "type": "string", "description": "Bank account number.", "example": "123456789" }, "bank_name": { "type": "string", "description": "Name of the bank.", "example": "Bank of America" }, "branch_code": { "type": "string", "example": "123456", "description": "Bank branch code (e.g. sort code, IFSC, BSB, etc.). Primarily used for international wires." }, "external_reference": { "type": "string", "nullable": true, "description": "Your own identifier for this payment instructions", "example": "payment-instructions-123" }, "type": { "type": "string", "description": "'ach'" }, "routing_number": { "type": "string", "description": "ABA routing number", "example": "021000021" } }, "required": [ "type" ], "additionalProperties": false, "description": "US ACH instructions" }, "DomesticWireInstructionsInput": { "type": "object", "properties": { "beneficiary_name": { "type": "string", "description": "Name of the account holder, as registered with the bank.", "example": "Jane Doe" }, "account_number": { "type": "string", "description": "Bank account number.", "example": "123456789" }, "bank_name": { "type": "string", "description": "Name of the bank.", "example": "Bank of America" }, "branch_code": { "type": "string", "example": "123456", "description": "Bank branch code (e.g. sort code, IFSC, BSB, etc.). Primarily used for international wires." }, "external_reference": { "type": "string", "nullable": true, "description": "Your own identifier for this payment instructions", "example": "payment-instructions-123" }, "intermediary_party_name": { "type": "string", "description": "Name of the intermediary bank.", "example": "Intermediary Bank" }, "intermediary_party_swift_code": { "type": "string", "description": "SWIFT/BIC code of the intermediary bank.", "example": "INTBANKXXX" }, "originator_to_beneficiary_instructions_line1": { "type": "string", "description": "Payment instructions line 1.", "example": "For further credit to Jane Doe" }, "originator_to_beneficiary_instructions_line2": { "type": "string", "description": "Payment instructions line 2.", "example": "Invoice 12345" }, "originator_to_beneficiary_instructions_line3": { "type": "string", "description": "Payment instructions line 3.", "example": "Attn Accounts Payable" }, "type": { "type": "string", "description": "'domestic_wire'" }, "routing_number": { "type": "string", "description": "ABA routing number", "example": "021000021" }, "address": { "$ref": "#/components/schemas/WireAddress" } }, "required": [ "type" ], "additionalProperties": false, "description": "US domestic wire instructions" }, "WireAddress": { "type": "object", "properties": { "street1": { "type": "string", "description": "Street address line 1. PO boxes are accepted but will be considered not yet valid.", "example": "123 Main St" }, "street2": { "type": "string", "description": "Street address line 2. PO boxes are accepted but will be considered not yet valid.", "example": "Suite 100" }, "city": { "type": "string", "description": "City", "example": "San Francisco" }, "state": { "type": "string", "description": "State or province. For US addresses must be exactly 2 chars.", "example": "CA" }, "postal_code": { "type": "string", "description": "Postal code. For US addresses, ZIP or ZIP+4.", "example": "94105" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "US" } }, "required": [ "street1", "city", "country_code" ], "additionalProperties": false }, "InternationalWireInstructionsInput": { "type": "object", "properties": { "beneficiary_name": { "type": "string", "description": "Name of the account holder, as registered with the bank.", "example": "Jane Doe" }, "account_number": { "type": "string", "description": "Bank account number.", "example": "123456789" }, "bank_name": { "type": "string", "description": "Name of the bank.", "example": "Bank of America" }, "branch_code": { "type": "string", "example": "123456", "description": "Bank branch code (e.g. sort code, IFSC, BSB, etc.). Primarily used for international wires." }, "external_reference": { "type": "string", "nullable": true, "description": "Your own identifier for this payment instructions", "example": "payment-instructions-123" }, "intermediary_party_name": { "type": "string", "description": "Name of the intermediary bank.", "example": "Intermediary Bank" }, "intermediary_party_swift_code": { "type": "string", "description": "SWIFT/BIC code of the intermediary bank.", "example": "INTBANKXXX" }, "originator_to_beneficiary_instructions_line1": { "type": "string", "description": "Payment instructions line 1.", "example": "For further credit to Jane Doe" }, "originator_to_beneficiary_instructions_line2": { "type": "string", "description": "Payment instructions line 2.", "example": "Invoice 12345" }, "originator_to_beneficiary_instructions_line3": { "type": "string", "description": "Payment instructions line 3.", "example": "Attn Accounts Payable" }, "type": { "type": "string", "description": "'international_wire'" }, "swift_code": { "type": "string", "description": "SWIFT/BIC code.", "example": "BOFAUS3N" }, "address": { "$ref": "#/components/schemas/WireAddress" } }, "required": [ "type" ], "additionalProperties": false, "description": "International wire instructions" }, "PaymentInstructions": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "payment_instructions" ], "description": "Object type identifier.", "example": "payment_instructions" }, "livemode": { "type": "boolean", "description": "Whether this object exists in live mode (`true`) or test mode (`false`)." }, "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^pmi_[A-Za-z0-9]+$", "description": "ID of the payment instructions", "example": "pmi_021wlGURMlk80cYuKBjENXqwC3OV" }, "entity": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^ent_[A-Za-z0-9]+$", "description": "ID of the entity these instructions belong to.", "example": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p" }, "external_reference": { "type": "string", "nullable": true, "description": "Your own identifier for this payment instructions", "example": "payment-instructions-123" }, "beneficiary_name": { "type": "string", "description": "Name of the account holder, as registered with the bank.", "example": "Jane Doe" }, "ach": { "$ref": "#/components/schemas/AchPaymentInstructions" }, "wire": { "$ref": "#/components/schemas/WirePaymentInstructions" }, "created_at": { "$ref": "#/components/schemas/UtcDateTime" }, "updated_at": { "$ref": "#/components/schemas/UtcDateTime" } }, "required": [ "object", "livemode", "id", "entity", "external_reference", "beneficiary_name", "created_at", "updated_at" ], "additionalProperties": false }, "AchPaymentInstructions": { "type": "object", "properties": { "routing_number": { "type": "string", "description": "ABA routing number", "example": "021000021" }, "account_number_last_four": { "type": "string", "description": "Last four digits of the account number.", "example": "6789" }, "bank_name": { "type": "string", "description": "Name of the bank.", "example": "Bank of America" } }, "required": [ "routing_number", "account_number_last_four" ] }, "WirePaymentInstructions": { "type": "object", "properties": { "bank_name": { "type": "string", "description": "Name of the bank.", "example": "Bank of America" }, "routing_number": { "type": "string", "description": "ABA routing number", "example": "021000021" }, "account_number_last_four": { "type": "string", "description": "Last four digits of the account number.", "example": "6789" }, "swift_code": { "type": "string", "description": "SWIFT/BIC code.", "example": "BOFAUS3N" }, "branch_code": { "type": "string", "example": "123456", "description": "Bank branch code (e.g. sort code, IFSC, BSB, etc.). Primarily used for international wires." }, "intermediary_party_name": { "type": "string", "description": "Name of the intermediary bank.", "example": "Intermediary Bank" }, "intermediary_party_swift_code": { "type": "string", "description": "SWIFT/BIC code of the intermediary bank.", "example": "INTBANKXXX" }, "is_international": { "type": "boolean", "description": "Whether this is an international wire." } }, "required": [ "bank_name", "account_number_last_four" ] }, "EntityList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier.", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Entity" }, "description": "The page of items." }, "next_page_url": { "type": "string", "nullable": true, "description": "URL for the next page of the list, or `null` when there are no more pages.", "example": "/v1/entities?page=page_5dr8SFDbv7rZ2aj4&limit=10" }, "previous_page_url": { "type": "string", "nullable": true, "description": "URL for the previous page of the list, or `null` when there are none.", "example": "/v1/entities?page_before=page_8VtqLBv3xJpY7mk2&limit=10" }, "has_more": { "type": "boolean", "description": "Whether there are more items available after this page. Deprecated: `next_page_url` is non-null exactly when more pages exist.", "deprecated": true }, "url": { "type": "string", "description": "Path identifying this list. Deprecated: on lists embedded in another object, or returned by a create, it may not be a GET endpoint you can call. Follow `next_page_url` / `previous_page_url` to paginate.", "example": "/v1/entities", "deprecated": true } }, "required": [ "object", "data", "next_page_url", "previous_page_url", "has_more", "url" ], "additionalProperties": false, "x-mint": { "post": [ "List" ] }, "description": "Type: [`List`](/types/list) _A page of results_" }, "Entity": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "entity" ], "description": "Object type identifier.", "example": "entity" }, "livemode": { "type": "boolean", "description": "Whether this object exists in live mode (`true`) or test mode (`false`)." }, "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^ent_[A-Za-z0-9]+$", "description": "ID of the entity", "example": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Legal name of the entity", "example": "Jane Doe, LLC" }, "type": { "$ref": "#/components/schemas/EntityType" }, "external_type": { "type": "string", "description": "Your own type for this entity" }, "external_reference": { "type": "string", "nullable": true, "description": "Your identifier for this entity", "example": "entity-123" }, "sender_payment_instructions_url": { "type": "string", "description": "URL to this entity's page in the sender's Nova app, opened on its payment methods tab where that tab is enabled.", "example": "https://nova.angellist.com/path_to_sender_payment_instructions" }, "recipient_payment_instructions_url": { "type": "string", "description": "URL to the recipient's wallet for this entity.", "example": "https://nova.angellist.com/path_to_recipient_wallet" }, "recipient_payment_instructions_verification_url": { "type": "string", "description": "URL where the recipient can confirm this entity's payment instructions.", "example": "https://nova.angellist.com/path_to_recipient_verification" }, "payment_instructions": { "$ref": "#/components/schemas/PaymentInstructionsList" } }, "required": [ "object", "livemode", "id", "name", "type", "external_reference", "sender_payment_instructions_url", "recipient_payment_instructions_url", "recipient_payment_instructions_verification_url", "payment_instructions" ], "additionalProperties": false }, "EntityType": { "type": "string", "enum": [ "individual", "individual_retirement_plan", "corporation", "llc", "partnership", "trust", "joint_tenants_ros", "tenants_in_common", "community_property", "registered_investment_company", "foundation", "charitable_remainder_trust", "endowment", "employee_benefit_plan", "keogh_plan", "other_entity" ], "example": "individual" }, "EntityCreateInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Legal name of the entity", "example": "Jane Doe, LLC" }, "type": { "$ref": "#/components/schemas/EntityType" }, "external_type": { "type": "string", "description": "Your own type for this entity" }, "external_reference": { "type": "string", "nullable": true, "description": "Your identifier for this entity", "example": "entity-123" } }, "required": [ "name", "type" ], "additionalProperties": false }, "ContactList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier.", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" }, "description": "The page of items." }, "next_page_url": { "type": "string", "nullable": true, "description": "URL for the next page of the list, or `null` when there are no more pages.", "example": "/v1/contacts?page=page_5dr8SFDbv7rZ2aj4&limit=10" }, "previous_page_url": { "type": "string", "nullable": true, "description": "URL for the previous page of the list, or `null` when there are none.", "example": "/v1/contacts?page_before=page_8VtqLBv3xJpY7mk2&limit=10" }, "has_more": { "type": "boolean", "description": "Whether there are more items available after this page. Deprecated: `next_page_url` is non-null exactly when more pages exist.", "deprecated": true }, "url": { "type": "string", "description": "Path identifying this list. Deprecated: on lists embedded in another object, or returned by a create, it may not be a GET endpoint you can call. Follow `next_page_url` / `previous_page_url` to paginate.", "example": "/v1/contacts", "deprecated": true } }, "required": [ "object", "data", "next_page_url", "previous_page_url", "has_more", "url" ], "additionalProperties": false, "x-mint": { "post": [ "List" ] }, "description": "Type: [`List`](/types/list) _A page of results_" }, "Contact": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "contact" ], "description": "Object type identifier.", "example": "contact" }, "livemode": { "type": "boolean", "description": "Whether this object exists in live mode (`true`) or test mode (`false`)." }, "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^cnt_[A-Za-z0-9]+$", "description": "ID of the contact", "example": "cnt_tSfCZrNE8O3c4QATSkzuCljMZ2DI" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Full legal name", "example": "Jane Doe" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "jane.doe@example.com" }, "external_reference": { "type": "string", "nullable": true, "description": "Your own identifier for this contact", "example": "contact-123" } }, "required": [ "object", "livemode", "id", "name", "email", "external_reference" ], "additionalProperties": false }, "ContactCreateInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Full legal name", "example": "Jane Doe" }, "email": { "type": "string", "format": "email", "description": "Email address", "example": "jane.doe@example.com" }, "external_reference": { "type": "string", "nullable": true, "description": "Your own identifier for this contact", "example": "contact-123" } }, "required": [ "name", "email" ], "additionalProperties": false }, "Organization": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "organization" ], "description": "Object type identifier.", "example": "organization" }, "livemode": { "type": "boolean", "description": "Whether this object exists in live mode (`true`) or test mode (`false`)." }, "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^org_[A-Za-z0-9]+$", "description": "ID of the organization", "example": "org_EkzhrUc3U6C0UbxNBlK7WLz51ofT" }, "name": { "type": "string", "description": "Name of the organization", "example": "Acme Capital" } }, "required": [ "object", "livemode", "id", "name" ], "additionalProperties": false }, "Vehicle": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "vehicle" ], "description": "Object type identifier.", "example": "vehicle" }, "livemode": { "type": "boolean", "description": "Whether this object exists in live mode (`true`) or test mode (`false`)." }, "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^veh_[A-Za-z0-9]+$", "description": "ID of the vehicle", "example": "veh_pNvehE6O1KjY2W6Omq9MD3QAEs5w" }, "name": { "type": "string", "description": "Name of the vehicle", "example": "Nova Ventures Fund I, LLC" }, "sender_entities_url": { "type": "string", "format": "uri", "description": "A link for the sender to review this vehicle's entities in the Nova dashboard.", "example": "https://nova.angellist.com/path_to_vehicle_entities" } }, "required": [ "object", "livemode", "id", "name", "sender_entities_url" ], "additionalProperties": false }, "FinancialAccountList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier.", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FinancialAccount" }, "description": "The page of items." }, "next_page_url": { "type": "string", "nullable": true, "description": "URL for the next page of the list, or `null` when there are no more pages.", "example": "/v1/vehicles/veh_pNvehE6O1KjY2W6Omq9MD3QAEs5w/financial_accounts?page=page_5dr8SFDbv7rZ2aj4&limit=10" }, "previous_page_url": { "type": "string", "nullable": true, "description": "URL for the previous page of the list, or `null` when there are none.", "example": "/v1/vehicles/veh_pNvehE6O1KjY2W6Omq9MD3QAEs5w/financial_accounts?page_before=page_8VtqLBv3xJpY7mk2&limit=10" }, "has_more": { "type": "boolean", "description": "Whether there are more items available after this page. Deprecated: `next_page_url` is non-null exactly when more pages exist.", "deprecated": true }, "url": { "type": "string", "description": "Path identifying this list. Deprecated: on lists embedded in another object, or returned by a create, it may not be a GET endpoint you can call. Follow `next_page_url` / `previous_page_url` to paginate.", "example": "/v1/vehicles/veh_pNvehE6O1KjY2W6Omq9MD3QAEs5w/financial_accounts", "deprecated": true } }, "required": [ "object", "data", "next_page_url", "previous_page_url", "has_more", "url" ], "additionalProperties": false, "x-mint": { "post": [ "List" ] }, "description": "Type: [`List`](/types/list) _A page of results_" }, "FinancialAccount": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "financial_account" ], "description": "Object type identifier.", "example": "financial_account" }, "livemode": { "type": "boolean", "description": "Whether this object exists in live mode (`true`) or test mode (`false`)." }, "id": { "type": "string", "minLength": 31, "maxLength": 31, "pattern": "^fa_[A-Za-z0-9]+$", "description": "ID of the financial account", "example": "fa_RoYxEYPaMtOgRX7lDYzfxVE14uPK" }, "vehicle": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^veh_[A-Za-z0-9]+$", "description": "ID of the vehicle that holds this account", "example": "veh_pNvehE6O1KjY2W6Omq9MD3QAEs5w" }, "name": { "type": "string", "description": "Name of the account", "example": "Acme Trust LLC (7862)" }, "type": { "$ref": "#/components/schemas/FinancialAccountType" }, "bank_name": { "type": "string", "nullable": true, "description": "Name of the partner bank that holds the account.", "example": "Goldman Lynch" }, "account_number_last_four": { "type": "string", "nullable": true, "description": "Last four digits.", "example": "7862" }, "balance": { "$ref": "#/components/schemas/FinancialAccountBalance" }, "created_at": { "$ref": "#/components/schemas/UtcDateTime" }, "updated_at": { "$ref": "#/components/schemas/UtcDateTime" } }, "required": [ "object", "livemode", "id", "vehicle", "name", "type", "bank_name", "account_number_last_four", "balance", "created_at", "updated_at" ], "additionalProperties": false }, "FinancialAccountType": { "type": "string", "enum": [ "depository", "brokerage" ], "example": "depository", "x-mint": { "post": [ "FinancialAccountType" ] }, "description": "Type: [`FinancialAccountType`](/types/financial-account#type) _Kind of account_" }, "FinancialAccountBalance": { "type": "object", "properties": { "total": { "type": "integer", "description": "Ledger balance plus outgoing wires and ACH pushes the bank has not debited yet. For a brokerage account, includes the invested position. Given in the smallest currency unit.", "example": 125000 }, "available": { "type": "integer", "description": "Total minus pending debits, plus pending credits. Given in the smallest currency unit.", "example": 125000 }, "pending_debit": { "type": "integer", "description": "Outgoing payments and holds not yet settled. Given in the smallest currency unit.", "example": 125000 }, "pending_credit": { "type": "integer", "description": "Incoming transfers not yet settled. Given in the smallest currency unit.", "example": 125000 }, "total_end_of_last_month": { "type": "integer", "description": "Total at the end of last month. Given in the smallest currency unit.", "example": 125000 }, "currency": { "$ref": "#/components/schemas/Currency" } }, "required": [ "total", "available", "pending_debit", "pending_credit", "total_end_of_last_month", "currency" ], "additionalProperties": false, "x-mint": { "post": [ "FinancialAccountBalance" ] }, "description": "Type: [`FinancialAccountBalance`](/types/financial-account#balance) _Balances in the smallest currency unit_" }, "TransactionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier.", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" }, "description": "The page of items." }, "next_page_url": { "type": "string", "nullable": true, "description": "URL for the next page of the list, or `null` when there are no more pages.", "example": "/v1/financial_accounts/fa_5dr8SFDbv7rZ2aj4/transactions?page=page_5dr8SFDbv7rZ2aj4&limit=10" }, "previous_page_url": { "type": "string", "nullable": true, "description": "URL for the previous page of the list, or `null` when there are none.", "example": "/v1/financial_accounts/fa_5dr8SFDbv7rZ2aj4/transactions?page_before=page_8VtqLBv3xJpY7mk2&limit=10" }, "has_more": { "type": "boolean", "description": "Whether there are more items available after this page. Deprecated: `next_page_url` is non-null exactly when more pages exist.", "deprecated": true }, "url": { "type": "string", "description": "Path identifying this list. Deprecated: on lists embedded in another object, or returned by a create, it may not be a GET endpoint you can call. Follow `next_page_url` / `previous_page_url` to paginate.", "example": "/v1/financial_accounts/fa_5dr8SFDbv7rZ2aj4/transactions", "deprecated": true } }, "required": [ "object", "data", "next_page_url", "previous_page_url", "has_more", "url" ], "additionalProperties": false, "x-mint": { "post": [ "List" ] }, "description": "Type: [`List`](/types/list) _A page of results_" }, "Transaction": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "transaction" ], "description": "Object type identifier.", "example": "transaction" }, "livemode": { "type": "boolean", "description": "Whether this object exists in live mode (`true`) or test mode (`false`)." }, "id": { "type": "string", "minLength": 31, "maxLength": 33, "pattern": "^tx_[A-Za-z0-9]+$", "description": "ID of the transaction", "example": "tx_jlZBEplxMpzsPGL9IdboNDvQ1jFV" }, "financial_account": { "type": "string", "minLength": 31, "maxLength": 31, "pattern": "^fa_[A-Za-z0-9]+$", "description": "ID of the financial account this transaction belongs to", "example": "fa_RoYxEYPaMtOgRX7lDYzfxVE14uPK" }, "source": { "$ref": "#/components/schemas/TransactionSource" }, "workflow": { "$ref": "#/components/schemas/TransactionWorkflow" }, "amount": { "type": "integer", "nullable": true, "example": -50000, "description": "Signed amount in cents. Positive amounts are credits, and negative amounts are debits. Can be null in some pending cases, but never once `settled_at` is set." }, "currency": { "$ref": "#/components/schemas/Currency" }, "balance": { "type": "integer", "nullable": true, "example": 950000, "description": "Running balance after the entry. Null when the bank holds no entry for the row." }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "description": { "type": "string", "nullable": true, "example": "Wire to Acme LLC, Chase **7862", "description": "Short label, when the bank supplies one." }, "created_at": { "$ref": "#/components/schemas/UtcDateTime" }, "updated_at": { "$ref": "#/components/schemas/UtcDateTime" }, "settled_at": { "allOf": [ { "$ref": "#/components/schemas/UtcDateTime" }, { "nullable": true } ] } }, "required": [ "object", "livemode", "id", "financial_account", "source", "workflow", "amount", "currency", "balance", "status", "description", "created_at", "updated_at", "settled_at" ], "additionalProperties": false }, "TransactionSource": { "oneOf": [ { "$ref": "#/components/schemas/TransactionWireSource", "title": "Wire" }, { "$ref": "#/components/schemas/TransactionOtherSource", "title": "Others" }, { "nullable": true, "title": "No source yet" } ], "x-mint": { "post": [ "TransactionSource" ] }, "description": "Type: [`TransactionSource`](/types/transaction#source) _What caused this entry. Null when the transaction has not reached the bank._" }, "TransactionWireSource": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "wire" ] }, "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^txg_[A-Za-z0-9]+$", "description": "Opaque grouping key. Every entry of one money movement repeats it (fees, reversals, returns).", "example": "txg_CHyy6emsi8QiwMa2Oe4uNn3Z0TVX" }, "memo": { "type": "string", "nullable": true, "description": "Originator-to-beneficiary information. Null means unknown, not empty." } }, "required": [ "type", "id", "memo" ], "additionalProperties": false, "description": "A wire sent from or received into this account. Carries the bank message fields." }, "TransactionOtherSource": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "ach", "transfer", "other" ] }, "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^txg_[A-Za-z0-9]+$", "description": "Opaque grouping key. Every entry of one money movement repeats it (fees, reversals, returns).", "example": "txg_CHyy6emsi8QiwMa2Oe4uNn3Z0TVX" } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "A non-wire bank payment (`ach`), an on-platform transfer, or any other cause." }, "TransactionWorkflow": { "oneOf": [ { "$ref": "#/components/schemas/TransactionDistributionWorkflow" }, { "nullable": true } ], "x-mint": { "post": [ "TransactionWorkflow" ] }, "description": "Type: [`TransactionWorkflow`](/types/transaction#workflow) _Nova workflow this transaction is related to (e.g. distribution). `null` for out-of-band bank activity, or non-nova related transactions. New workflow types will be added._" }, "TransactionDistributionWorkflow": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "distribution" ] }, "id": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^dst_[A-Za-z0-9]+$", "description": "ID of the distribution", "example": "dst_tQaOR74NP2DZ9mg3votpOnCqAuGs" }, "payment": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^dpmt_[A-Za-z0-9]+$", "description": "ID of the distribution payment", "example": "dpmt_sSTfFdsytyOearj36zDNcmXn1pJ4" }, "entity": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^ent_[A-Za-z0-9]+$", "description": "ID of the entity the payment went to", "example": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p" } }, "required": [ "type", "id", "payment", "entity" ], "additionalProperties": false, "description": "A distribution payment." }, "TransactionStatus": { "type": "string", "enum": [ "pending", "processing", "completed", "rejected", "returned", "cancelled", "failed", "unknown" ], "example": "completed", "x-mint": { "post": [ "TransactionStatus" ] }, "description": "Type: [`TransactionStatus`](/types/transaction#status) _Where the transaction is in its lifecycle_" } }, "parameters": { "OrganizationId": { "schema": { "$ref": "#/components/schemas/OrganizationId" }, "required": false, "description": "ID of the organization the request acts on. Optional when the access token is bound to a specific `organization`, or when the integration has access to exactly one organization.", "name": "X-Organization-Id", "in": "header" }, "IdempotencyKey": { "schema": { "$ref": "#/components/schemas/IdempotencyKey" }, "required": false, "description": "Only applies to POST, PUT, PATCH, and DELETE; ignored on reads.\n\nType: [`IdempotencyKey`](/types/idempotency-key) _A unique key that makes a mutating request safely retryable, kept for 24 hours_", "name": "Idempotency-Key", "in": "header" } } }, "paths": { "/v1/distributions": { "post": { "operationId": "createDistributions", "summary": "Create distributions", "description": "Create and publish one fund distribution. The request body is an array that must contain exactly one distribution. The created distribution is `published`, and its payments start as `staged`. Each distribution has one or more payments; each payment references an existing entity by ID (`entity`) and an optional list of contacts to notify (`notifications[].contact`). Create entities and contacts first via `POST /v1/entities` and `POST /v1/contacts`.\n\nCreating a distribution also associates the records it references:\n\n- Each contact in `notifications[].contact` is associated with the `entity` on the same payment.\n- Each payment `entity` is associated with the distribution `vehicle`.", "tags": [ "Distributions" ], "security": [ { "OAuth2": [ "distributions:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DistributionCreateInput" }, "minItems": 1, "maxItems": 1 } } } }, "responses": { "201": { "description": "Distribution created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistributionList" } } } }, "400": { "description": "Validation error, including unknown entity, contact or vehicle IDs, or a vehicle with no bank account for payouts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A distribution with this `external_reference` already exists, or the Idempotency-Key is in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listDistributions", "summary": "List distributions", "description": "List distributions with pagination, optionally filtered to specific ids", "tags": [ "Distributions" ], "security": [ { "OAuth2": [ "distributions:read" ] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The maximum number of items to return." }, "required": false, "description": "The maximum number of items to return.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "example": "page_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "required": false, "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "name": "page", "in": "query" }, { "schema": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "example": "page_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "required": false, "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "name": "page_before", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^dst_[A-Za-z0-9]+$", "example": "dst_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "minItems": 1, "maxItems": 100, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, or `limit`." }, "required": false, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, or `limit`.", "name": "id", "in": "query" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "List of distributions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DistributionList" } } } }, "400": { "description": "Invalid pagination parameters, `id` filter, or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/distributions/{id}": { "get": { "operationId": "getDistribution", "summary": "Retrieve a distribution", "description": "Retrieve a single distribution by ID.", "tags": [ "Distributions" ], "security": [ { "OAuth2": [ "distributions:read" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^dst_[A-Za-z0-9]+$", "description": "ID of the distribution", "example": "dst_tQaOR74NP2DZ9mg3votpOnCqAuGs" }, "required": true, "description": "ID of the distribution", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "Distribution details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Distribution" } } } }, "400": { "description": "Invalid request, such as a malformed ID or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Distribution not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payment_instructions": { "post": { "operationId": "createPaymentInstructions", "summary": "Create payment instructions", "description": "Create one or more payment instructions for one or more entities in a single request. Partial instructions are supported. The batch is atomic — if any fail to be created, none are created.", "tags": [ "Payment Instructions", "Entities" ], "security": [ { "OAuth2": [ "entities:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityPaymentInstructionsInput" }, "minItems": 1 } } } }, "responses": { "201": { "description": "Payment instructions created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityPaymentInstructionsList" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "One or more entities not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "One or more payment instructions already exist, or the Idempotency-Key is in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payment_instructions/{id}": { "get": { "operationId": "getPaymentInstructions", "summary": "Retrieve payment instructions", "description": "Retrieve a single payment instructions record by ID. Some fields are omitted in the response.", "tags": [ "Payment Instructions", "Entities" ], "security": [ { "OAuth2": [ "entities:read" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^pmi_[A-Za-z0-9]+$", "description": "ID of the payment instructions", "example": "pmi_021wlGURMlk80cYuKBjENXqwC3OV" }, "required": true, "description": "ID of the payment instructions", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "Payment instructions details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentInstructions" } } } }, "400": { "description": "Invalid request, such as a malformed ID or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Payment instructions not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/entities": { "post": { "operationId": "createEntities", "summary": "Create entities", "description": "Create one or more entities associated with the organization in a single request. The batch is atomic — if any entity fails, none are created.", "tags": [ "Entities" ], "security": [ { "OAuth2": [ "entities:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EntityCreateInput" }, "minItems": 1 } } } }, "responses": { "201": { "description": "Entities created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityList" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Entity with these external references already exists, or the Idempotency-Key is in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listEntities", "summary": "List entities", "description": "List entities with pagination, optionally filtered to specific ids", "tags": [ "Entities" ], "security": [ { "OAuth2": [ "entities:read" ] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The maximum number of items to return." }, "required": false, "description": "The maximum number of items to return.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "example": "page_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "required": false, "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "name": "page", "in": "query" }, { "schema": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "example": "page_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "required": false, "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "name": "page_before", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^ent_[A-Za-z0-9]+$", "example": "ent_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "minItems": 1, "maxItems": 100, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, or `limit`." }, "required": false, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, or `limit`.", "name": "id", "in": "query" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "List of entities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityList" } } } }, "400": { "description": "Invalid pagination parameters, `id` filter, or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/entities/{id}": { "get": { "operationId": "getEntity", "summary": "Retrieve an entity", "description": "Retrieve a single entity by ID.", "tags": [ "Entities" ], "security": [ { "OAuth2": [ "entities:read" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^ent_[A-Za-z0-9]+$", "description": "ID of the entity", "example": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p" }, "required": true, "description": "ID of the entity", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "Entity details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } }, "400": { "description": "Invalid request, such as a malformed ID or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/entities/{ent_id}/contacts": { "post": { "operationId": "associateEntityContacts", "summary": "Associate contacts with an entity", "description": "Associate one or more existing contacts with an entity. Idempotent — contacts already associated are left as they are.", "tags": [ "Entities" ], "security": [ { "OAuth2": [ "entities:write" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^ent_[A-Za-z0-9]+$", "description": "ID of the entity", "example": "ent_H0hdMOc5E5QMTEcGVZKegvLNCB6p" }, "required": true, "description": "ID of the entity", "name": "ent_id", "in": "path" }, { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContactRef" }, "minItems": 1, "maxItems": 100 } } } }, "responses": { "200": { "description": "Contacts associated with the entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" } } } }, "400": { "description": "Invalid entity ID, contact IDs, or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Entity or one or more contacts not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency-Key is in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contacts": { "post": { "operationId": "createContacts", "summary": "Create contacts", "description": "Create one or more contacts associated with the organization in a single request. The batch is atomic — if any contact fails validation, none are created.", "tags": [ "Contacts" ], "security": [ { "OAuth2": [ "contacts:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/OrganizationId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContactCreateInput" }, "minItems": 1 } } } }, "responses": { "201": { "description": "Contacts created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Contact with this email or external reference already exists, or the Idempotency-Key is in use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Idempotency-Key reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listContacts", "summary": "List contacts", "description": "List contacts with pagination, optionally filtered to specific ids", "tags": [ "Contacts" ], "security": [ { "OAuth2": [ "contacts:read" ] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The maximum number of items to return." }, "required": false, "description": "The maximum number of items to return.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "example": "page_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "required": false, "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "name": "page", "in": "query" }, { "schema": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "example": "page_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "required": false, "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "name": "page_before", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^cnt_[A-Za-z0-9]+$", "example": "cnt_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "minItems": 1, "maxItems": 100, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, or `limit`." }, "required": false, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, or `limit`.", "name": "id", "in": "query" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "List of contacts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" } } } }, "400": { "description": "Invalid pagination parameters, `id` filter, or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/contacts/{id}": { "get": { "operationId": "getContact", "summary": "Retrieve a contact", "description": "Retrieve a single contact by ID.", "tags": [ "Contacts" ], "security": [ { "OAuth2": [ "contacts:read" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^cnt_[A-Za-z0-9]+$", "description": "ID of the contact", "example": "cnt_tSfCZrNE8O3c4QATSkzuCljMZ2DI" }, "required": true, "description": "ID of the contact", "name": "id", "in": "path" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "Contact details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "description": "Invalid request, such as a malformed ID or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/organizations/{org_id}": { "get": { "operationId": "getOrganization", "summary": "Retrieve an organization", "description": "Retrieve the organization the API credentials belong to.", "tags": [ "Organizations" ], "security": [ { "OAuth2": [ "organizations:read" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^org_[A-Za-z0-9]+$", "description": "ID of the organization", "example": "org_EkzhrUc3U6C0UbxNBlK7WLz51ofT" }, "required": true, "description": "ID of the organization", "name": "org_id", "in": "path" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Invalid request, such as a malformed ID or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/vehicles/{veh_id}": { "get": { "operationId": "getVehicle", "summary": "Retrieve a vehicle", "description": "Retrieve a single vehicle by ID.", "tags": [ "Vehicles" ], "security": [ { "OAuth2": [ "vehicles:read" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^veh_[A-Za-z0-9]+$", "description": "ID of the vehicle", "example": "veh_pNvehE6O1KjY2W6Omq9MD3QAEs5w" }, "required": true, "description": "ID of the vehicle", "name": "veh_id", "in": "path" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "Vehicle details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Vehicle" } } } }, "400": { "description": "Invalid request, such as a malformed ID or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Vehicle not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/financial_accounts": { "get": { "operationId": "listFinancialAccounts", "summary": "List an organization's financial accounts", "description": "List the financial accounts across every vehicle in the organization, newest first, optionally filtered to specific ids.", "tags": [ "Financial Accounts" ], "security": [ { "OAuth2": [ "financial_accounts:read" ] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The maximum number of items to return." }, "required": false, "description": "The maximum number of items to return.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "example": "page_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "required": false, "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "name": "page", "in": "query" }, { "schema": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "example": "page_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "required": false, "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "name": "page_before", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 31, "maxLength": 31, "pattern": "^fa_[A-Za-z0-9]+$", "example": "fa_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "minItems": 1, "maxItems": 100, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, or `limit`." }, "required": false, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, or `limit`.", "name": "id", "in": "query" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "List of financial accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialAccountList" } } } }, "400": { "description": "Invalid pagination parameters, `id` filter, or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/financial_accounts/{fa_id}": { "get": { "operationId": "getFinancialAccount", "summary": "Retrieve a financial account", "description": "Retrieve one financial account a vehicle in the organization holds.", "tags": [ "Financial Accounts" ], "security": [ { "OAuth2": [ "financial_accounts:read" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 31, "maxLength": 31, "pattern": "^fa_[A-Za-z0-9]+$", "description": "ID of the financial account", "example": "fa_RoYxEYPaMtOgRX7lDYzfxVE14uPK" }, "required": true, "description": "ID of the financial account", "name": "fa_id", "in": "path" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "The financial account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialAccount" } } } }, "400": { "description": "Invalid financial account ID or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Financial account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/financial_accounts/{fa_id}/transactions": { "get": { "operationId": "listFinancialAccountTransactions", "summary": "List a financial account's transactions", "description": "List a financial account's transactions, newest first.", "tags": [ "Financial Accounts" ], "security": [ { "OAuth2": [ "financial_accounts:read" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 31, "maxLength": 31, "pattern": "^fa_[A-Za-z0-9]+$", "description": "ID of the financial account", "example": "fa_RoYxEYPaMtOgRX7lDYzfxVE14uPK" }, "required": true, "description": "ID of the financial account", "name": "fa_id", "in": "path" }, { "schema": { "type": "string", "enum": [ "created_at", "settled_at" ], "default": "settled_at", "description": "Sort by creation or settlement time, newest first. When sorting by `settled_at`, transactions where `settled_at: null` are listed first." }, "required": false, "description": "Sort by creation or settlement time, newest first. When sorting by `settled_at`, transactions where `settled_at: null` are listed first.", "name": "sort_by", "in": "query" }, { "schema": { "allOf": [ { "$ref": "#/components/schemas/DateOrDateTime" }, { "description": "Filter results where `sort_by` time is at or after this.\n\n**Note:** when sorting by `settled_at`, specifying `after` skips transactions where `settled_at: null`.\n\nType: [`DateOrDateTime`](/types/date-or-date-time) _ISO 8601 Date or Date and time_" } ] }, "required": false, "description": "Filter results where `sort_by` time is at or after this.\n\n**Note:** when sorting by `settled_at`, specifying `after` skips transactions where `settled_at: null`.\n\nType: [`DateOrDateTime`](/types/date-or-date-time) _ISO 8601 Date or Date and time_", "name": "after", "in": "query" }, { "schema": { "allOf": [ { "$ref": "#/components/schemas/DateOrDateTime" }, { "description": "Filter results where `sort_by` time is before this.\n\nThe bound is exclusive, so `before=2026-02-01T00:00:00` includes values until 23:59:59 January 31, 2026.\n\nType: [`DateOrDateTime`](/types/date-or-date-time) _ISO 8601 Date or Date and time_" } ] }, "required": false, "description": "Filter results where `sort_by` time is before this.\n\nThe bound is exclusive, so `before=2026-02-01T00:00:00` includes values until 23:59:59 January 31, 2026.\n\nType: [`DateOrDateTime`](/types/date-or-date-time) _ISO 8601 Date or Date and time_", "name": "before", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "description": "The maximum number of items to return." }, "required": false, "description": "The maximum number of items to return.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 48, "maxLength": 367, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "example": "page_V8rYrurkxXEHmnqsLn8OUJXrWWhmgPkiLSuIz7OkgNL" }, "required": false, "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "name": "page", "in": "query" }, { "schema": { "type": "string", "minLength": 48, "maxLength": 367, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "example": "page_V8rYrurkxXEHmnqsLn8OUJXrWWhmgPkiLSuIz7OkgNL" }, "required": false, "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "name": "page_before", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 31, "maxLength": 33, "pattern": "^tx_[A-Za-z0-9]+$", "example": "tx_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "minItems": 1, "maxItems": 100, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, `limit`, `after`, or `before`." }, "required": false, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, `limit`, `after`, or `before`.", "name": "id", "in": "query" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "List of transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionList" } } } }, "400": { "description": "Invalid financial account ID, pagination parameters, `id` filter, or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Financial account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/financial_accounts/{fa_id}/transactions/{tx_id}": { "get": { "operationId": "getFinancialAccountTransaction", "summary": "Retrieve a financial account transaction", "description": "Retrieve one transaction of a financial account by the `id` the transactions list returned.", "tags": [ "Financial Accounts" ], "security": [ { "OAuth2": [ "financial_accounts:read" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 31, "maxLength": 31, "pattern": "^fa_[A-Za-z0-9]+$", "description": "ID of the financial account", "example": "fa_RoYxEYPaMtOgRX7lDYzfxVE14uPK" }, "required": true, "description": "ID of the financial account", "name": "fa_id", "in": "path" }, { "schema": { "type": "string", "minLength": 31, "maxLength": 33, "pattern": "^tx_[A-Za-z0-9]+$", "description": "ID of the transaction", "example": "tx_jlZBEplxMpzsPGL9IdboNDvQ1jFV" }, "required": true, "description": "ID of the transaction", "name": "tx_id", "in": "path" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "The transaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } }, "400": { "description": "Invalid financial account or transaction ID, or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Financial account or transaction not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/vehicles/{veh_id}/financial_accounts": { "get": { "operationId": "listVehicleFinancialAccounts", "summary": "List a vehicle's financial accounts", "description": "List the financial accounts a vehicle holds, optionally filtered to specific ids.", "tags": [ "Financial Accounts" ], "security": [ { "OAuth2": [ "financial_accounts:read" ] } ], "parameters": [ { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "pattern": "^veh_[A-Za-z0-9]+$", "description": "ID of the vehicle", "example": "veh_pNvehE6O1KjY2W6Omq9MD3QAEs5w" }, "required": true, "description": "ID of the vehicle", "name": "veh_id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "The maximum number of items to return." }, "required": false, "description": "The maximum number of items to return.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "example": "page_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "required": false, "description": "Opaque cursor from a previous response `next_page_url`; returns the results after it", "name": "page", "in": "query" }, { "schema": { "type": "string", "minLength": 33, "maxLength": 33, "pattern": "^page_[A-Za-z0-9]+$", "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "example": "page_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "required": false, "description": "Opaque cursor from a previous response `previous_page_url`; returns the results before it", "name": "page_before", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "minLength": 31, "maxLength": 31, "pattern": "^fa_[A-Za-z0-9]+$", "example": "fa_5dr8SFDbv7rZ2aj4Qm9XcLpT2wHk" }, "minItems": 1, "maxItems": 100, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, or `limit`." }, "required": false, "description": "Return only the resources with these ids. Repeat the parameter for each id (max 100). All matches return in one page.\n\nNOTE: cannot be combined with `page`, `page_before`, or `limit`.", "name": "id", "in": "query" }, { "$ref": "#/components/parameters/OrganizationId" } ], "responses": { "200": { "description": "List of financial accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinancialAccountList" } } } }, "400": { "description": "Invalid vehicle ID, pagination parameters, `id` filter, or `X-Organization-Id` header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Missing required OAuth scope or organization access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Vehicle not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded", "headers": { "Retry-After": { "schema": { "type": "integer", "description": "Seconds until the rate-limit window resets. Present on 429 responses." }, "required": true, "description": "Seconds until the rate-limit window resets. Present on 429 responses." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }