{ "openapi": "3.0.0", "paths": { "/organizations": { "get": { "description": "Retrieves a paginated list of organizations the authenticated user belongs to", "operationId": "listOrganizations", "parameters": [ { "name": "first", "required": false, "in": "query", "description": "Number of items to return", "schema": { "minimum": 1, "maximum": 100, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of organizations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOrganizationsResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "organizations:read", "organizations:all" ] } ], "summary": "List organizations", "tags": [ "organizations" ] } }, "/organizations/{organizationId}": { "get": { "description": "Retrieves detailed information about a specific organization", "operationId": "getOrganization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "The unique identifier of the organization (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "organizations:read", "organizations:all" ] } ], "summary": "Get organization", "tags": [ "organizations" ] }, "put": { "description": "Updates an organization with the provided name and/or email domain name", "operationId": "updateOrganization", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "The unique identifier of the organization (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Organization data to update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationInfoDto" } } } }, "responses": { "200": { "description": "Successfully updated the organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "organizations:all" ] } ], "summary": "Update organization", "tags": [ "organizations" ] } }, "/organizations/{organizationId}/logo": { "put": { "description": "Uploads the logo shown next to the organization, replacing any previous one. Accepts PNG, JPEG and WebP; the real file signature is checked, not the declared type, so an SVG is refused. Maximum size: 2MB. Without a logo, one is derived from emailDomainName at display time and nothing is stored.", "operationId": "setOrganizationLogo", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "The unique identifier of the organization (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Logo image", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadOrganizationLogoDto" } } } }, "responses": { "200": { "description": "Successfully set the organization logo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data or file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Payload Too Large - File size exceeds limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "organizations:all" ] } ], "summary": "Set organization logo", "tags": [ "organizations" ] }, "delete": { "description": "Removes the uploaded logo. Display falls back to a logo derived from emailDomainName, then to the name initials.", "operationId": "removeOrganizationLogo", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "The unique identifier of the organization (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully removed the organization logo", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "organizations:all" ] } ], "summary": "Remove organization logo", "tags": [ "organizations" ] } }, "/organizations/{organizationId}/settings": { "put": { "description": "Updates organization settings. Only the fields present in the body are applied; send an explicit null to clear one. `letterDetails` is replaced as a whole: send its four fields together, since a field left out of it is cleared.", "operationId": "updateOrganizationSettings", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "The unique identifier of the organization (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Organization settings data to update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationSettingsDto" } } } }, "responses": { "200": { "description": "Successfully updated the organization settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrganizationResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Organization not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "organizations:all" ] } ], "summary": "Update organization settings", "tags": [ "organizations" ] } }, "/organizations/{organizationId}/invitations": { "post": { "description": "Sends an invitation email to a user to join the organization", "operationId": "createOrganizationInvitation", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "The unique identifier of the organization (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Invitation payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitationDto" } } } }, "responses": { "201": { "description": "Successfully sent the invitation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "organizations:all" ] } ], "summary": "Invite user to organization", "tags": [ "organizations" ] } }, "/organizations/{organizationId}/invitations/{email}": { "delete": { "description": "Cancels a pending invitation to the organization", "operationId": "deleteOrganizationInvitation", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "The unique identifier of the organization (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "email", "required": true, "in": "path", "description": "Email address of the invitation to cancel (URL encoded)", "schema": { "example": "user%40example.com", "type": "string" } } ], "responses": { "204": { "description": "Successfully cancelled the invitation" }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Invitation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "organizations:all" ] } ], "summary": "Cancel organization invitation", "tags": [ "organizations" ] } }, "/organizations/{organizationId}/members": { "get": { "description": "Retrieves a list of all members of the organization", "operationId": "listOrganizationMembers", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "The unique identifier of the organization (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of members", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MemberResponseDto" } } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "organizations:read", "organizations:all" ] } ], "summary": "List organization members", "tags": [ "organizations" ] } }, "/organizations/{organizationId}/members/{userId}": { "delete": { "description": "Removes a member from the organization", "operationId": "deleteOrganizationMember", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "The unique identifier of the organization (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "userId", "required": true, "in": "path", "description": "Unique identifier of the user to remove (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001", "type": "string" } } ], "responses": { "204": { "description": "Successfully removed the member" }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "organizations:all" ] } ], "summary": "Remove organization member", "tags": [ "organizations" ] } }, "/organizations/{organizationId}/tags": { "get": { "description": "Retrieves the tags available to the organization, custom and predefined. The list is short and is not paginated.", "operationId": "listTags", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "The unique identifier of the organization (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the list of tags", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TagResponseDto" } } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:read", "accounts:all" ] } ], "summary": "List tags", "tags": [ "tags" ] }, "post": { "description": "Creates a custom tag owned by the organization", "operationId": "createTag", "parameters": [ { "name": "organizationId", "required": true, "in": "path", "description": "The unique identifier of the organization (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Tag to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagDto" } } } }, "responses": { "201": { "description": "Successfully created the tag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Create tag", "tags": [ "tags" ] } }, "/users/me/avatar": { "put": { "description": "Uploads or replaces the authenticated user profile picture. Accepts PNG, JPEG and WebP up to 2MB.", "operationId": "setMyAvatar", "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/UploadUserAvatarDto" } } } }, "responses": { "200": { "description": "Successfully set the profile picture", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data or file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Payload Too Large - File size exceeds limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "profile" ] } ], "summary": "Set my profile picture", "tags": [ "user-profile" ] }, "delete": { "description": "Removes the authenticated user profile picture.", "operationId": "removeMyAvatar", "parameters": [], "responses": { "200": { "description": "Successfully removed the profile picture", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "profile" ] } ], "summary": "Remove my profile picture", "tags": [ "user-profile" ] } }, "/accounts": { "get": { "description": "Retrieves a paginated list of accounts for the specified organization. Without \"filters\" the list is served from the aggregate store and its cursors keep their historical format; with \"filters\" it is served from the account list projection and the cursor is bound to the conditions it was issued for.", "operationId": "listAccounts", "parameters": [ { "name": "first", "required": false, "in": "query", "description": "Number of items to return. The default applies to the filtered or sorted list; a plain call without either keeps its historical unbounded streaming.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID v4) of the organization", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "filters", "required": false, "in": "query", "description": "Filter conditions. Available fields: `accountName` (contains, startsWith, equals); `tags` (containsAny, containsAll, containsNone, isEmpty, isNotEmpty); `dunningPaused` (isTrue, isFalse); `daysOverdue`, `overdueInvoiceCount`, `overdueBalance`, `remainingBalance` (equals, greaterThan, lessThan, between); `hasPaymentSchedule` (isTrue, isFalse); `paymentMethod` (is, isNot, isAnyOf, isEmpty, isNotEmpty); `collectiveProceeding` (is, isNot, isAnyOf: Yes, No, Unknown); `source` (is, isNot, isAnyOf, isEmpty, isNotEmpty).", "schema": { "maxLength": 8000, "example": "dunningPaused:isFalse;accountName:contains:acme", "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "Field to sort on. Sorting is resolved by the account list projection, so asking for one switches the list to that projection even without filters, and binds the cursor to it.", "schema": { "default": "fullName", "type": "string", "enum": [ "fullName", "overdueInvoiceCount", "overdueBalance", "remainingBalance" ] } }, { "name": "sortOrder", "required": false, "in": "query", "description": "Sort direction", "schema": { "default": "asc", "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAccountsResponseDto" } } } }, "400": { "description": "Bad Request - invalid pagination parameters, unreadable filter conditions (LIST_FILTER_INVALID), or a cursor issued for a different set of filters (LIST_CURSOR_INVALID)\n\nBad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:read", "accounts:all" ] } ], "summary": "List accounts", "tags": [ "accounts" ] }, "post": { "description": "Creates a new account for the specified organization", "operationId": "createAccount", "parameters": [], "requestBody": { "required": true, "description": "Account data to create", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAccountDto" } } } }, "responses": { "201": { "description": "Successfully created the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Create account", "tags": [ "accounts" ] } }, "/accounts/{accountId}": { "get": { "description": "Retrieves detailed information about a specific account", "operationId": "getAccount", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:read", "accounts:all" ] } ], "summary": "Get account", "tags": [ "accounts" ] }, "put": { "description": "Updates an existing account with the provided information", "operationId": "updateAccount", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Account data to update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAccountDto" } } } }, "responses": { "200": { "description": "Successfully updated the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Update account", "tags": [ "accounts" ] }, "delete": { "description": "Permanently deletes an account and all associated data", "operationId": "deleteAccount", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "204": { "description": "Successfully deleted the account" }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Delete account", "tags": [ "accounts" ] } }, "/accounts/{accountId}/financial-overview": { "get": { "description": "Explains the customer balance and returns every past and future invoice installment", "operationId": "getAccountFinancialOverview", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the account financial overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountOperationalBalanceResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account financial overview not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:read", "accounts:all" ] } ], "summary": "Get account financial overview", "tags": [ "accounts" ] } }, "/accounts/{accountId}/source": { "put": { "description": "Links a custom source reference to the account. When an account has a custom source, it is considered managed via API and cannot be excluded via the UI blacklist. This endpoint is idempotent: if the same source is already linked, only the lastUpdate date will be updated.", "operationId": "linkAccountSource", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Source reference data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSourceRefDto" } } } }, "responses": { "200": { "description": "Successfully linked the source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found\n\nSource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Link source", "tags": [ "source" ] }, "patch": { "description": "Updates the lastUpdate date of an existing source reference. Only accounts with Custom sources can be updated via the API. If lastUpdate is not provided, defaults to the current date/time.", "operationId": "updateAccountSourceLastUpdate", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Source update data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSourceRefDto" } } } }, "responses": { "200": { "description": "Successfully updated the source", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found or source not linked\n\nSource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Update source sync date", "tags": [ "source" ] }, "delete": { "description": "Removes the custom source reference from the account. Only accounts with Custom sources can be unlinked via the API.", "operationId": "unlinkAccountSource", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "204": { "description": "Successfully unlinked the source" }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found\n\nSource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Unlink source", "tags": [ "source" ] } }, "/accounts/{accountId}/tags": { "post": { "description": "Attaches existing tags to the account. Tags are applied one by one and the first unknown tag stops the request, so the tags listed before it stay attached. Attaching a tag the account already has changes nothing.", "operationId": "assignAccountTags", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Tags to attach to the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignAccountTagsDto" } } } }, "responses": { "204": { "description": "Successfully attached the tags" }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account or tag not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Attach tags to an account", "tags": [ "accounts" ] } }, "/accounts/{accountId}/tags/{tagId}": { "delete": { "description": "Detaches a tag from the account. The tag itself is not deleted.", "operationId": "removeAccountTag", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "tagId", "required": true, "in": "path", "description": "The unique identifier of the tag to detach (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001", "type": "string" } } ], "responses": { "204": { "description": "Successfully detached the tag" }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Detach a tag from an account", "tags": [ "accounts" ] } }, "/accounts/{accountId}/contacts": { "get": { "description": "Retrieves all contacts associated with an account", "operationId": "listAccountContacts", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the contacts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContactResponseDto" } } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:read", "accounts:all" ] } ], "summary": "List contacts", "tags": [ "contacts" ] }, "post": { "description": "Adds a new contact to the specified account", "operationId": "addAccountContact", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Contact data to add", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactDto" } } } }, "responses": { "201": { "description": "Successfully added the contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Add contact", "tags": [ "contacts" ] } }, "/accounts/{accountId}/contacts/{contactId}": { "get": { "description": "Retrieves detailed information about a specific contact", "operationId": "getAccountContact", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "contactId", "required": true, "in": "path", "description": "The unique identifier of the contact (UUID v4)", "schema": { "format": "uuid", "example": "987fcdeb-51a2-3b4c-d5e6-789012345678", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:read", "accounts:all" ] } ], "summary": "Get contact", "tags": [ "contacts" ] }, "put": { "description": "Updates an existing contact with the provided information", "operationId": "updateAccountContact", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "contactId", "required": true, "in": "path", "description": "The unique identifier of the contact (UUID v4)", "schema": { "format": "uuid", "example": "987fcdeb-51a2-3b4c-d5e6-789012345678", "type": "string" } } ], "requestBody": { "required": true, "description": "Contact data to update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContactDto" } } } }, "responses": { "200": { "description": "Successfully updated the contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Update contact", "tags": [ "contacts" ] }, "delete": { "description": "Removes a contact from the account", "operationId": "removeAccountContact", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "contactId", "required": true, "in": "path", "description": "The unique identifier of the contact (UUID v4)", "schema": { "format": "uuid", "example": "987fcdeb-51a2-3b4c-d5e6-789012345678", "type": "string" } } ], "responses": { "204": { "description": "Successfully removed the contact" }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Remove contact", "tags": [ "contacts" ] } }, "/accounts/{accountId}/contacts/{contactId}/enabled": { "put": { "description": "Enables or disables a contact. Disabled contacts are never proactively contacted by the AI agent.", "operationId": "setAccountContactEnabled", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "contactId", "required": true, "in": "path", "description": "The unique identifier of the contact (UUID v4)", "schema": { "format": "uuid", "example": "987fcdeb-51a2-3b4c-d5e6-789012345678", "type": "string" } } ], "requestBody": { "required": true, "description": "Enabled status to set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetContactEnabledDto" } } } }, "responses": { "200": { "description": "Successfully updated the contact enabled status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Enable or disable contact", "tags": [ "contacts" ] } }, "/accounts/{accountId}/contact-enrichment/candidates": { "get": { "description": "Lists up to ten people on the customer side who look like they handle supplier payments (accounting, collections, treasury, finance leadership). Free of charge, and returns no contact details. Fails when the credit balance could not pay for a single enrichment, since the list would lead nowhere.", "operationId": "searchAccountContactCandidates", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the candidates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ContactCandidateResponseDto" } } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:read", "accounts:all" ] } ], "summary": "Search contact candidates", "tags": [ "contacts" ] } }, "/accounts/{accountId}/contact-enrichment": { "post": { "description": "Buys a contact's details: 1 credit for an email address, 2 as soon as a phone number is found, 0 when nothing is found. Returns as soon as the provider accepted; the contact is created on the account about a minute later, whether or not the caller is still connected. Nothing has to be polled.", "operationId": "enrichAccountContact", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Who to look for", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichContactDto" } } } }, "responses": { "201": { "description": "The enrichment was accepted by the provider", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactEnrichmentResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account or contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Enrich a contact", "tags": [ "contacts" ] } }, "/accounts/{accountId}/contacts/upsert": { "put": { "description": "Creates a new contact or updates an existing one based on email or name matching. If no match is found, fullName and language are required to create a new contact.", "operationId": "upsertAccountContact", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Contact data to upsert", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertContactDto" } } } }, "responses": { "200": { "description": "Successfully upserted the contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found\n\nContact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "accounts:all" ] } ], "summary": "Upsert contact", "tags": [ "contacts" ] } }, "/invoices": { "get": { "description": "Retrieves a paginated list of invoices for the specified organization. Optional conditions go in \"filters\", written \"field:operator\" or \"field:operator:value,value\" with percent-encoded values, several conditions joined by \";\" and combined with AND. A cursor is only valid for the filters it was issued with.", "operationId": "listInvoices", "parameters": [ { "name": "first", "required": false, "in": "query", "description": "Number of items to return. The default applies to the filtered or sorted list; a plain call without either keeps its historical unbounded streaming.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID v4) of the organization", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "filters", "required": false, "in": "query", "description": "Filter conditions. Available fields: `number`, `accountName` (contains, startsWith, equals); `tags` (containsAny, containsAll, containsNone, isEmpty, isNotEmpty: the labels carried by the account this document belongs to); `status` (is, isNot, isAnyOf: Issued, Paid, Overdue); `dueDate` (on, before, after, between); `paymentSchedule` (isTrue, isFalse); `paymentMethod` (is, isNot, isAnyOf, isEmpty, isNotEmpty); `totalAmount`, `remainingBalance` (equals, greaterThan, lessThan, between); `channel` (is, isNot, isAnyOf); `sourceId` (is, isAnyOf, isEmpty, isNotEmpty: case-sensitive, the caller-provided identifier).", "schema": { "maxLength": 8000, "example": "status:isAnyOf:Overdue,Issued;accountName:contains:acme", "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "Field to sort on. Sorting is resolved by the invoice list projection, so asking for one switches the list to that projection even without filters, and binds the cursor to it.", "schema": { "default": "number", "type": "string", "enum": [ "number", "accountFullName", "status", "dueDate", "totalAmount", "remainingBalance" ] } }, { "name": "sortOrder", "required": false, "in": "query", "description": "Sort direction", "schema": { "default": "asc", "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of invoices", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedInvoicesResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters\n\nInvalid pagination parameters, unreadable \"filters\", or an \"after\" cursor issued for a different set of filters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "invoices:read", "invoices:all" ] } ], "summary": "List invoices", "tags": [ "invoices" ] }, "post": { "description": "Creates a new invoice with an attached document file (PDF or image). Supports both binary and base64 file encoding. For base64, set the Content-Transfer-Encoding header to \"base64\" in the file part. Maximum file size: 10MB (decoded binary size).", "operationId": "createInvoice", "parameters": [], "requestBody": { "required": true, "description": "Invoice data with file attachment", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateInvoiceDto" } } } }, "responses": { "201": { "description": "Successfully created the invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data or file\n\nBusiness rules are refused with a 400, not a 409, and the `code` says which one: `app-invoicing.invoice.duplicate-source-id` when \"sourceId\" is already used in the organization, `app-invoicing.invoice.duplicate-number` when the account already has an invoice with that number. The same number on another account is accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Payload Too Large - File size exceeds limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "invoices:all" ] } ], "summary": "Create invoice", "tags": [ "invoices" ] } }, "/invoices/{invoiceId}": { "get": { "description": "Retrieves detailed information about a specific invoice", "operationId": "getInvoice", "parameters": [ { "name": "invoiceId", "required": true, "in": "path", "description": "The unique identifier of the invoice (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the invoice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceDetailResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "invoices:read", "invoices:all" ] } ], "summary": "Get invoice", "tags": [ "invoices" ] }, "delete": { "description": "Permanently deletes an invoice", "operationId": "deleteInvoice", "parameters": [ { "name": "invoiceId", "required": true, "in": "path", "description": "The unique identifier of the invoice (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "204": { "description": "Successfully deleted the invoice" }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "invoices:all" ] } ], "summary": "Delete invoice", "tags": [ "invoices" ] } }, "/invoices/{invoiceId}/paid-amount": { "put": { "description": "Updates the paid amount on a specific invoice", "operationId": "updateInvoicePaidAmount", "parameters": [ { "name": "invoiceId", "required": true, "in": "path", "description": "The unique identifier of the invoice (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Paid amount payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetInvoicePaidAmountDto" } } } }, "responses": { "200": { "description": "Successfully updated the paid amount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "invoices:all" ] } ], "summary": "Update invoice paid amount", "tags": [ "invoices" ] } }, "/invoices/{invoiceId}/payment-schedule": { "put": { "description": "Replaces the complete payment schedule. Send an empty installments array to remove it.", "operationId": "updateInvoicePaymentSchedule", "parameters": [ { "name": "invoiceId", "required": true, "in": "path", "description": "The unique identifier of the invoice (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetInvoicePaymentScheduleDto" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Invoice not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "invoices:all" ] } ], "summary": "Update invoice payment schedule", "tags": [ "invoices" ] } }, "/credit-notes": { "get": { "description": "Retrieves a paginated list of credit notes for the specified organization. Optional conditions go in \"filters\", written \"field:operator\" or \"field:operator:value,value\" with percent-encoded values, several conditions joined by \";\". Available fields: `number`, `accountName` (contains, startsWith, equals); `tags` (containsAny, containsAll, containsNone, isEmpty, isNotEmpty: the labels carried by the account this document belongs to); `status` (is, isNot, isAnyOf: Issued, PartiallySettled, Settled); `issuedDate` (on, before, after, between); `paymentMethod` (is, isNot, isAnyOf, isEmpty, isNotEmpty); `totalAmount`, `remainingAmount` (equals, greaterThan, lessThan, between); `channel` (is, isNot, isAnyOf); `sourceId` (is, isAnyOf, isEmpty, isNotEmpty: case-sensitive, the caller-provided identifier). A cursor belongs to the exact set of filters and sort it was issued with: reusing it with different ones is refused, drop \"after\" and read the first page again.", "operationId": "listCreditNotes", "parameters": [ { "name": "first", "required": false, "in": "query", "description": "Number of items to return. The default applies to the filtered or sorted list; a plain call without either keeps its historical unbounded streaming.", "schema": { "minimum": 1, "maximum": 100, "default": 20, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID v4) of the organization", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "filters", "required": false, "in": "query", "description": "Filter conditions, joined by \";\", each written \"field:operator\" or \"field:operator:value,value\" with percent-encoded values", "schema": { "maxLength": 8000, "example": "status:isAnyOf:Overdue,Issued;accountName:contains:acme", "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "Field to sort on. Sorting is resolved by the credit note list projection, so asking for one switches the list to that projection even without filters, and binds the cursor to it.", "schema": { "default": "issuedDate", "type": "string", "enum": [ "number", "accountFullName", "status", "issuedDate", "totalAmount", "remainingAmount" ] } }, { "name": "sortOrder", "required": false, "in": "query", "description": "Sort direction", "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of credit notes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCreditNotesResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters\n\nInvalid pagination parameters, unreadable \"filters\", or a cursor issued for a different set of filters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "credit-notes:read", "credit-notes:all" ] } ], "summary": "List credit notes", "tags": [ "credit-notes" ] }, "post": { "description": "Creates a new credit note with an attached document file (PDF or image). Supports both binary and base64 file encoding. For base64, set the Content-Transfer-Encoding header to \"base64\" in the file part. Maximum file size: 10MB (decoded binary size).", "operationId": "createCreditNote", "parameters": [], "requestBody": { "required": true, "description": "Credit note data with file attachment", "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateCreditNoteDto" } } } }, "responses": { "201": { "description": "Successfully created the credit note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data or file\n\nBusiness rules are refused with a 400, not a 409, and the `code` says which one: `app-invoicing.credit-note.duplicate-source-id` when \"sourceId\" is already used in the organization, `app-invoicing.credit-note.duplicate-number` when the account already has a credit note with that number. The same number on another account is accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Payload Too Large - File size exceeds limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "credit-notes:all" ] } ], "summary": "Create credit note", "tags": [ "credit-notes" ] } }, "/credit-notes/{creditNoteId}": { "get": { "description": "Retrieves detailed information about a specific credit note", "operationId": "getCreditNote", "parameters": [ { "name": "creditNoteId", "required": true, "in": "path", "description": "The unique identifier of the credit note (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the credit note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteDetailResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Credit note not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "credit-notes:read", "credit-notes:all" ] } ], "summary": "Get credit note", "tags": [ "credit-notes" ] }, "delete": { "description": "Permanently deletes a credit note", "operationId": "deleteCreditNote", "parameters": [ { "name": "creditNoteId", "required": true, "in": "path", "description": "The unique identifier of the credit note (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "204": { "description": "Successfully deleted the credit note" }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Credit note not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "credit-notes:all" ] } ], "summary": "Delete credit note", "tags": [ "credit-notes" ] } }, "/credit-notes/{creditNoteId}/refunded-amount": { "put": { "description": "Updates the refunded amount on a specific credit note", "operationId": "updateCreditNoteRefundedAmount", "parameters": [ { "name": "creditNoteId", "required": true, "in": "path", "description": "The unique identifier of the credit note (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Refunded amount payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCreditNoteRefundedAmountDto" } } } }, "responses": { "200": { "description": "Successfully updated the refunded amount", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditNoteResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Credit note not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "credit-notes:all" ] } ], "summary": "Update credit note refunded amount", "tags": [ "credit-notes" ] } }, "/credit-allocations": { "post": { "description": "Applies a credit amount from a credit note to an invoice, reducing the outstanding balance", "operationId": "applyCreditAllocation", "parameters": [], "requestBody": { "required": true, "description": "Credit allocation payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyCreditAllocationDto" } } } }, "responses": { "201": { "description": "Successfully applied the credit allocation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditAllocationResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "invoices:all", "credit-notes:all" ] } ], "summary": "Apply credit allocation", "tags": [ "credit-allocations" ] } }, "/credit-allocations/remove": { "post": { "description": "Removes a credit allocation, reversing the credit applied to the invoice", "operationId": "removeCreditAllocation", "parameters": [], "requestBody": { "required": true, "description": "Credit allocation payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyCreditAllocationDto" } } } }, "responses": { "204": { "description": "Successfully removed the credit allocation" }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Credit allocation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "invoices:all", "credit-notes:all" ] } ], "summary": "Remove credit allocation", "tags": [ "credit-allocations" ] } }, "/accounts/{accountId}/dunning": { "get": { "description": "Returns why automated payment follow-up is or is not running on a customer account right now: the suspensions in force and who posted them, any dated hold, and every condition holding the next reminder back (connector data too old to send on, a balance under the follow-up floor, the date the first reminder becomes eligible).", "operationId": "getAccountDunningStatus", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "The current dunning status of the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDunningStatusResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "dunning:manage" ] } ], "summary": "Read the dunning status of an account", "tags": [ "accounts" ] } }, "/accounts/{accountId}/dunning/pause": { "post": { "description": "Suspends automated payment follow-up for a customer account. Fact reasons stay paused until resumed. Dated wait reasons require until and resume automatically. Omitting the body creates a manual pause.", "operationId": "pauseAccountDunning", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PauseAccountDunningDto" } } } }, "responses": { "201": { "description": "Successfully paused dunning for the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDunningStatusResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "dunning:manage" ] } ], "summary": "Pause dunning for an account", "tags": [ "accounts" ] } }, "/accounts/{accountId}/dunning/resume": { "post": { "description": "Resumes automated dunning (follow-up emails) for a customer account previously suspended. Lifts the manual pause, the ones the platform posted on itself, and the ones a person may name (stop requested, dispute, payment plan, legal proceedings). Suspensions nothing but their own fix can lift stay in place: insolvency proceedings, an unlinked source, a connector needing reconnection. The response carries the remaining `pauseReasons`, and an account that still has some keeps `isDunningPaused: true`.", "operationId": "resumeAccountDunning", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "201": { "description": "Successfully resumed dunning for the account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountDunningStatusResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "dunning:manage" ] } ], "summary": "Resume dunning for an account", "tags": [ "accounts" ] } }, "/customer-outstanding-balances": { "get": { "description": "Retrieves a paginated list of customer outstanding balances for the specified organization", "operationId": "listCustomerOutstandingBalances", "parameters": [ { "name": "first", "required": false, "in": "query", "description": "Number of items to return", "schema": { "minimum": 1, "maximum": 100, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID v4) of the organization", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of customer outstanding balances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCustomerOutstandingBalancesResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "List customer outstanding balances", "tags": [ "customer-outstanding-balances" ] } }, "/customer-outstanding-balances/{balanceId}": { "get": { "description": "Retrieves a specific customer outstanding balance by its ID with associated invoices and credit notes", "operationId": "getCustomerOutstandingBalance", "parameters": [ { "name": "balanceId", "required": true, "in": "path", "description": "The unique identifier of the customer outstanding balance (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the customer outstanding balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerOutstandingBalanceResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Customer outstanding balance not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "Get customer outstanding balance", "tags": [ "customer-outstanding-balances" ] } }, "/communications": { "get": { "description": "Retrieves a paginated list of communications, incoming and outgoing together. Filter with the \"filters\" parameter, whose conditions are joined by \";\" and written \"field:operator\" or \"field:operator:value,value\" with percent-encoded values. Available fields and operators: direction (is, isNot, isAnyOf: Incoming, Outgoing), status (is, isNot, isAnyOf), deliveryStatus (is, isNot, isAnyOf, isEmpty, isNotEmpty), accountName / contactName / subject (contains, startsWith, equals, isEmpty, isNotEmpty), date (on, before, after, between, values written YYYY-MM-DD). Example: \"direction:is:Incoming;accountName:contains:acme\".", "operationId": "listCommunications", "parameters": [ { "name": "filters", "required": false, "in": "query", "description": "Filter conditions, joined by \";\", each written \"field:operator\" or \"field:operator:value,value\" with percent-encoded values", "schema": { "maxLength": 8000, "example": "status:isAnyOf:Overdue,Issued;accountName:contains:acme", "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID v4) of the organization", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "accountId", "required": false, "in": "query", "description": "Restrict the list to a single account", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "first", "required": false, "in": "query", "description": "Number of items to return", "schema": { "minimum": 1, "maximum": 100, "default": 20, "example": 20, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor returned as \"endCursor\" by the previous page. A cursor is bound to the filters and sort order it was issued for: changing either one invalidates it and the list must be read again from its first page.", "schema": { "example": "v2:9f2a1c4b7e10:2", "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "Field to sort on", "schema": { "default": "communicationAt", "type": "string", "enum": [ "communicationAt", "accountFullName", "contactFullName", "status" ] } }, { "name": "sortOrder", "required": false, "in": "query", "description": "Sort direction", "schema": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of communications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedCommunicationsResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters\n\nBad Request: an unreadable filter condition, an unknown field or operator (LIST_FILTER_INVALID), or a cursor issued for a different set of filters or sort order (LIST_CURSOR_INVALID). In the latter case, drop \"after\" and read the list again from its first page.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "List communications", "tags": [ "communications" ] } }, "/outgoing-email-communications": { "get": { "description": "Retrieves a paginated list of outgoing email communications for the specified organization", "operationId": "listOutgoingEmailCommunications", "parameters": [ { "name": "first", "required": false, "in": "query", "description": "Number of items to return", "schema": { "minimum": 1, "maximum": 100, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID v4) of the organization", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of outgoing email communications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOutgoingEmailCommunicationsResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "List outgoing email communications", "tags": [ "outgoing-email-communications" ] } }, "/outgoing-email-communications/{communicationId}": { "get": { "description": "Retrieves a specific outgoing email communication by its ID with embedded email details", "operationId": "getOutgoingEmailCommunication", "parameters": [ { "name": "communicationId", "required": true, "in": "path", "description": "The unique identifier of the outgoing email communication (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the outgoing email communication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutgoingEmailCommunicationResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Outgoing email communication not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "Get outgoing email communication", "tags": [ "outgoing-email-communications" ] }, "put": { "description": "Updates an outgoing email communication by modifying the scheduled email. Only emails that have not been sent yet can be modified. Use the message field in markdown for email content; the platform renders HTML/text and appends the agent signature automatically.", "operationId": "updateOutgoingEmailCommunication", "parameters": [ { "name": "communicationId", "required": true, "in": "path", "description": "The unique identifier of the outgoing email communication (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Outgoing email communication update payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOutgoingEmailCommunicationDto" } } } }, "responses": { "200": { "description": "Successfully updated the outgoing email communication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutgoingEmailCommunicationResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Outgoing email communication not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "dunning:manage" ] } ], "summary": "Update outgoing email communication", "tags": [ "outgoing-email-communications" ] } }, "/accounts/{accountId}/outgoing-email-communications": { "get": { "description": "Retrieves a paginated list of outgoing email communications for the specified account", "operationId": "listOutgoingEmailCommunicationsByAccount", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "first", "required": false, "in": "query", "description": "Number of items to return", "schema": { "minimum": 1, "maximum": 100, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of outgoing email communications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOutgoingEmailCommunicationsResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "List outgoing email communications by account", "tags": [ "outgoing-email-communications" ] }, "post": { "description": "Sends an email immediately, at the account level, on behalf of the AI agent. Recipients are free-form (not limited to the account contacts). The account next planned communication is automatically recomputed after the send. Use the message field in markdown for email content; the platform renders HTML/text and appends the agent signature automatically.", "operationId": "sendOutgoingEmailCommunication", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Outgoing email communication send payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendOutgoingEmailCommunicationDto" } } } }, "responses": { "201": { "description": "Successfully sent the outgoing email communication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutgoingEmailCommunicationResponseDto" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "dunning:manage" ] } ], "summary": "Send outgoing email communication", "tags": [ "outgoing-email-communications" ] } }, "/accounts/{accountId}/outgoing-letters/preview": { "post": { "deprecated": true, "description": "Renders the selected invoices and credit notes without spending credits. The returned amount and page count are the ones used by the send endpoint.", "operationId": "previewOutgoingLetter", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The account UUID", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewOutgoingLetterDto" } } } }, "responses": { "201": { "description": "Successfully rendered the postal reminder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutgoingLetterPreviewResponseDto" } } } } }, "security": [ { "OAuth2": [ "dunning:manage" ] } ], "summary": "Preview a postal reminder", "tags": [ "outgoing-letters" ] } }, "/accounts/{accountId}/outgoing-letters": { "post": { "deprecated": true, "description": "Sends a tracked or registered French letter, deducts only the selected credit notes, appends the selected evidence, and charges the rendered page count.", "operationId": "sendOutgoingLetter", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The account UUID", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendOutgoingLetterDto" } } } }, "responses": { "201": { "description": "Successfully sent the postal reminder", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutgoingLetterResponseDto" } } } } }, "security": [ { "OAuth2": [ "dunning:manage" ] } ], "summary": "Send a postal reminder", "tags": [ "outgoing-letters" ] } }, "/accounts/{accountId}/outgoing-message-communications/preview": { "post": { "operationId": "previewOutgoingMessageCommunication", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewOutgoingMessageCommunicationDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutgoingMessageCommunicationPreviewResponseDto" } } } }, "400": { "description": "Invalid message input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "dunning:manage" ] } ], "summary": "Preview and price an SMS or postal reminder", "tags": [ "outgoing-message-communications" ], "description": "Preview and price an SMS or postal reminder" } }, "/accounts/{accountId}/outgoing-message-communications": { "post": { "description": "This paid and irreversible operation supports a stable idempotency key and a maximum credit amount.", "operationId": "sendOutgoingMessageCommunication", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendOutgoingMessageCommunicationDto" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutgoingMessageCommunicationResponseDto" } } } }, "400": { "description": "Invalid message input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "402": { "description": "Insufficient credits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Provider send failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "dunning:manage" ] } ], "summary": "Send an SMS or postal reminder", "tags": [ "outgoing-message-communications" ] } }, "/accounts/{accountId}/outgoing-message-communications/{communicationId}": { "get": { "operationId": "getOutgoingMessageCommunication", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "communicationId", "required": true, "in": "path", "description": "The outgoing message communication UUID", "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutgoingMessageCommunicationResponseDto" } } } }, "404": { "description": "Communication not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "Get an outgoing SMS or postal reminder", "tags": [ "outgoing-message-communications" ], "description": "Get an outgoing SMS or postal reminder" } }, "/incoming-email-communications": { "get": { "description": "Retrieves a paginated list of incoming email communications for the specified organization", "operationId": "listIncomingEmailCommunications", "parameters": [ { "name": "first", "required": false, "in": "query", "description": "Number of items to return", "schema": { "minimum": 1, "maximum": 100, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID v4) of the organization", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of incoming email communications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedIncomingEmailCommunicationsResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "List incoming email communications", "tags": [ "incoming-email-communications" ] } }, "/incoming-email-communications/{communicationId}": { "get": { "description": "Retrieves a specific incoming email communication by its ID with embedded email details", "operationId": "getIncomingEmailCommunication", "parameters": [ { "name": "communicationId", "required": true, "in": "path", "description": "The unique identifier of the incoming email communication (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the incoming email communication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomingEmailCommunicationResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Incoming email communication not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "Get incoming email communication", "tags": [ "incoming-email-communications" ] } }, "/accounts/{accountId}/incoming-email-communications": { "get": { "description": "Retrieves a paginated list of incoming email communications for the specified account", "operationId": "listIncomingEmailCommunicationsByAccount", "parameters": [ { "name": "accountId", "required": true, "in": "path", "description": "The unique identifier of the account (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "first", "required": false, "in": "query", "description": "Number of items to return", "schema": { "minimum": 1, "maximum": 100, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of incoming email communications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedIncomingEmailCommunicationsResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "List incoming email communications by account", "tags": [ "incoming-email-communications" ] } }, "/account-tasks": { "get": { "description": "Retrieves active account tasks filtered by account and type. Account tasks are created by the Billabex agent when user input is required.", "operationId": "listAccountTasks", "parameters": [ { "name": "accountId", "required": true, "in": "query", "description": "Account ID to filter account tasks", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "type", "required": false, "in": "query", "description": "Account task type to filter", "schema": { "example": "NeedUserInput", "type": "string", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ] } } ], "responses": { "200": { "description": "Successfully retrieved active account tasks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AccountTaskResponseDto" } } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "tasks:read", "tasks:all" ] } ], "summary": "List active account tasks", "tags": [ "account-tasks" ] } }, "/account-tasks/search": { "get": { "description": "Retrieves a paginated list of account tasks for the organization, with optional filter conditions and sorting. Filterable fields: title (contains, startsWith, equals), accountName (contains, startsWith, equals), status, type (is, isNot, isAnyOf), tags (containsAny, containsAll, containsNone, isEmpty, isNotEmpty), balance (equals, greaterThan, lessThan, between, isEmpty, isNotEmpty), createdAt (on, before, after, between), updatedAt (on, before, after, between, isEmpty, isNotEmpty).", "operationId": "searchAccountTasks", "parameters": [ { "name": "filters", "required": false, "in": "query", "description": "Filter conditions, joined by \";\", each written \"field:operator\" or \"field:operator:value,value\" with percent-encoded values", "schema": { "maxLength": 8000, "example": "status:isAnyOf:Overdue,Issued;accountName:contains:acme", "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID v4) of the organization", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "accountId", "required": false, "in": "query", "description": "Restrict the list to a single account", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } }, { "name": "first", "required": false, "in": "query", "description": "Number of items to return", "schema": { "minimum": 1, "maximum": 100, "default": 20, "example": 20, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor of the next page, as returned by \"pageInfo.endCursor\". It is bound to the filters and sort of the call that produced it", "schema": { "example": "v2:8f14e45fceea:2", "type": "string" } }, { "name": "query", "required": false, "in": "query", "description": "Free text search on the task title and the account name", "schema": { "example": "acme", "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "Column to sort on", "schema": { "example": "createdAt", "type": "string", "enum": [ "createdAt", "updatedAt", "title", "accountFullName", "status", "balance" ] } }, { "name": "sortOrder", "required": false, "in": "query", "description": "Sort direction", "schema": { "example": "desc", "type": "string", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of account tasks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedAccountTaskListResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters\n\nInvalid filter condition (LIST_FILTER_INVALID), or a cursor that was issued for different filters or sorting (LIST_CURSOR_INVALID)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "tasks:read", "tasks:all" ] } ], "summary": "Search account tasks", "tags": [ "account-tasks" ] } }, "/account-tasks/{accountTaskId}": { "get": { "description": "Retrieves an account task by its ID. Account tasks are created by the Billabex agent when user input is required.", "operationId": "getAccountTask", "parameters": [ { "name": "accountTaskId", "required": true, "in": "path", "description": "Account Task ID (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved account task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountTaskResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "tasks:read", "tasks:all" ] } ], "summary": "Get account task", "tags": [ "account-tasks" ] } }, "/account-tasks/{accountTaskId}/cancel": { "post": { "description": "Cancels an account task by its ID, optionally recording why. Cancelling a task that gates dunning hands the cadence back to the agent, so the reason is what keeps that decision readable afterwards.", "operationId": "cancelAccountTask", "parameters": [ { "name": "accountTaskId", "required": true, "in": "path", "description": "Account Task ID (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelAccountTaskDto" } } } }, "responses": { "200": { "description": "Successfully canceled account task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountTaskResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Account task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "tasks:all" ] } ], "summary": "Cancel account task", "tags": [ "account-tasks" ] } }, "/account-tasks/{accountTaskId}/interactions": { "post": { "description": "Adds a user interaction to an account task. This is how users respond to tasks created by the Billabex agent.", "operationId": "addAccountTaskInteraction", "parameters": [ { "name": "accountTaskId", "required": true, "in": "path", "description": "Account Task ID (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "requestBody": { "required": true, "description": "Interaction payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAccountTaskInteractionEnvelopeDto" } } } }, "responses": { "200": { "description": "Successfully added interaction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InteractionResponseDto" } } } }, "400": { "description": "Bad Request - Invalid input data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "tasks:all" ] } ], "summary": "Add account task interaction", "tags": [ "account-tasks" ] } }, "/emails": { "get": { "description": "Retrieves a paginated list of all emails (incoming and outgoing) for the specified organization", "operationId": "listEmails", "parameters": [ { "name": "first", "required": false, "in": "query", "description": "Number of items to return", "schema": { "minimum": 1, "maximum": 100, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID v4) of the organization", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of emails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedEmailsResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "List all emails", "tags": [ "emails" ] } }, "/outgoing-emails": { "get": { "description": "Retrieves a paginated list of outgoing emails for the specified organization", "operationId": "listOutgoingEmails", "parameters": [ { "name": "first", "required": false, "in": "query", "description": "Number of items to return", "schema": { "minimum": 1, "maximum": 100, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID v4) of the organization", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of outgoing emails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedOutgoingEmailsResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "List outgoing emails", "tags": [ "outgoing-emails" ] } }, "/outgoing-emails/{emailId}": { "get": { "description": "Retrieves a specific outgoing email by its ID", "operationId": "getOutgoingEmail", "parameters": [ { "name": "emailId", "required": true, "in": "path", "description": "The unique identifier of the outgoing email (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the outgoing email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OutgoingEmailResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Outgoing email not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "Get outgoing email", "tags": [ "outgoing-emails" ] } }, "/incoming-emails": { "get": { "description": "Retrieves a paginated list of incoming emails for the specified organization", "operationId": "listIncomingEmails", "parameters": [ { "name": "first", "required": false, "in": "query", "description": "Number of items to return", "schema": { "minimum": 1, "maximum": 100, "example": 10, "type": "number" } }, { "name": "after", "required": false, "in": "query", "description": "Cursor for pagination, represents the last item of the previous page", "schema": { "example": "YXJyYXljb25uZWN0aW9uOjEx", "type": "string" } }, { "name": "organizationId", "required": true, "in": "query", "description": "The unique identifier (UUID v4) of the organization", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the paginated list of incoming emails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedIncomingEmailsResponseDto" } } } }, "400": { "description": "Bad Request - Invalid pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "List incoming emails", "tags": [ "incoming-emails" ] } }, "/incoming-emails/{emailId}": { "get": { "description": "Retrieves a specific incoming email by its ID", "operationId": "getIncomingEmail", "parameters": [ { "name": "emailId", "required": true, "in": "path", "description": "The unique identifier of the incoming email (UUID v4)", "schema": { "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000", "type": "string" } } ], "responses": { "200": { "description": "Successfully retrieved the incoming email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncomingEmailResponseDto" } } } }, "401": { "description": "Unauthorized - Invalid or missing OAuth token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } }, "headers": { "WWW-Authenticate": { "description": "Bearer challenge pointing to RFC 9728 protected-resource metadata.", "schema": { "type": "string" } } } }, "403": { "description": "Forbidden - Insufficient scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Incoming email not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "OAuth2": [ "communications:read", "dunning:manage" ] } ], "summary": "Get incoming email", "tags": [ "incoming-emails" ] } } }, "info": { "title": "Billabex Public API", "description": "External API for third-party integrations. Protected by OAuth 2.0.", "version": "1.0", "contact": {} }, "tags": [ { "name": "account-tasks", "x-displayName": "Account Tasks" }, { "name": "accounts", "x-displayName": "Accounts" }, { "name": "communications", "x-displayName": "Communications" }, { "name": "contacts", "x-displayName": "Contacts" }, { "name": "credit-allocations", "x-displayName": "Credit Allocations" }, { "name": "credit-notes", "x-displayName": "Credit Notes" }, { "name": "customer-outstanding-balances", "x-displayName": "Customer Outstanding Balances" }, { "name": "emails", "x-displayName": "Emails" }, { "name": "incoming-email-communications", "x-displayName": "Incoming Email Communications" }, { "name": "incoming-emails", "x-displayName": "Incoming Emails" }, { "name": "invoices", "x-displayName": "Invoices" }, { "name": "organizations", "x-displayName": "Organizations" }, { "name": "outgoing-email-communications", "x-displayName": "Outgoing Email Communications" }, { "name": "outgoing-emails", "x-displayName": "Outgoing Emails" }, { "name": "outgoing-letters", "x-displayName": "Outgoing Letters" }, { "name": "outgoing-message-communications", "x-displayName": "Outgoing Message Communications" }, { "name": "source", "x-displayName": "Source" }, { "name": "tags", "x-displayName": "Tags" }, { "name": "user-profile", "x-displayName": "User Profile" } ], "servers": [ { "url": "https://next.billabex.com/api/public/v1", "description": "Billabex production API" } ], "components": { "securitySchemes": { "OAuth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://next.billabex.com/api/oauth/authorize", "tokenUrl": "https://next.billabex.com/api/oauth/token", "scopes": { "openid": "openid", "profile": "profile", "email": "email", "invoices:read": "invoices:read", "invoices:all": "invoices:all", "credit-notes:read": "credit-notes:read", "credit-notes:all": "credit-notes:all", "accounts:read": "accounts:read", "accounts:all": "accounts:all", "communications:read": "communications:read", "dunning:manage": "dunning:manage", "tasks:read": "tasks:read", "tasks:all": "tasks:all", "organizations:read": "organizations:read", "organizations:all": "organizations:all", "mcp:read": "mcp:read", "mcp:write": "mcp:write", "sync": "sync" }, "x-usePkce": "SHA-256" } } } }, "schemas": { "AgentResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the agent (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "name": { "type": "string", "description": "Display name of the agent", "example": "Alex" }, "fullName": { "type": "string", "description": "Full name of the agent", "example": "Alex Johnson" }, "hiredDate": { "type": "string", "description": "Date when the agent was hired (ISO 8601 format)", "example": "2024-03-15T14:30:00Z", "nullable": true }, "firedDate": { "type": "string", "description": "Date when the agent was fired (ISO 8601 format)", "example": "2024-06-15T14:30:00Z", "nullable": true } }, "required": [ "id", "name", "fullName", "hiredDate", "firedDate" ] }, "ReminderDelayDirection": { "type": "string", "enum": [ "BEFORE", "AFTER" ], "description": "Which side of the due date the reminder falls on" }, "ReminderDelayResponseDto": { "type": "object", "properties": { "days": { "type": "number", "description": "Whole days between the due date and the first reminder", "example": 2 }, "direction": { "description": "Which side of the due date the reminder falls on", "example": "AFTER", "allOf": [ { "$ref": "#/components/schemas/ReminderDelayDirection" } ] } }, "required": [ "days", "direction" ] }, "SenderAddressResponseDto": { "type": "object", "properties": { "street": { "type": "string", "description": "Street line of the creditor address", "example": "10 rue de Penthievre" }, "postalCode": { "type": "string", "description": "Five-digit French postal code", "example": "75008" }, "city": { "type": "string", "description": "City of the creditor address", "example": "Paris" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code", "example": "FR" } }, "required": [ "street", "postalCode", "city", "country" ] }, "LetterDetailsResponseDto": { "type": "object", "properties": { "senderAddress": { "description": "Address the postal reminder is sent from. Null until it is filled in.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/SenderAddressResponseDto" } ] }, "siren": { "type": "string", "description": "Nine-digit French registration number of the creditor. Stored and returned, not printed on the letter yet.", "example": "123456789", "nullable": true }, "iban": { "type": "string", "description": "Account the debtor is asked to pay into, printed on postal reminders.", "example": "FR7630006000011234567890189", "nullable": true }, "bic": { "type": "string", "description": "BIC of the account above. Null when only the IBAN is known.", "example": "AGRIFRPP881", "nullable": true } }, "required": [ "senderAddress", "siren", "iban", "bic" ] }, "OrganizationLogoResponseDto": { "type": "object", "properties": { "filestoreId": { "type": "string", "description": "Identifier of the stored file, downloadable at /api/file/{id}", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "filename": { "type": "string", "description": "Original filename of the uploaded logo", "example": "logo.png" }, "uploadedByUserId": { "type": "string", "description": "Identifier of the user who uploaded the logo", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "uploadedAt": { "type": "string", "description": "Upload date in ISO 8601 format", "example": "2026-08-07T10:30:00Z" } }, "required": [ "filestoreId", "filename", "uploadedByUserId", "uploadedAt" ] }, "OrganizationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "name": { "type": "string", "description": "Name of the organization", "example": "Acme Corporation" }, "registrationDate": { "type": "string", "description": "Registration date of the organization in ISO 8601 format", "example": "2024-01-15T10:30:00Z" }, "emailDomainName": { "type": "string", "description": "Email domain name associated with the organization", "example": "acme.com", "nullable": true }, "memberIds": { "description": "List of member IDs belonging to the organization", "example": [ "123e4567-e89b-12d3-a456-426614174001" ], "items": { "type": "array", "items": { "type": "string" } }, "type": "array" }, "invitations": { "description": "List of pending invitation email addresses", "example": [ "newmember@acme.com" ], "items": { "type": "array", "items": { "type": "string" } }, "type": "array" }, "agents": { "type": "array", "items": { "description": "List of agents associated with the organization", "type": "array", "items": { "$ref": "#/components/schemas/AgentResponseDto" } } }, "currentAgent": { "description": "Currently active agent for the organization", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/AgentResponseDto" } ] }, "lastAgentHiredDate": { "type": "string", "description": "Date when the last agent was hired in ISO 8601 format", "example": "2024-03-15T14:30:00Z", "nullable": true }, "nextAgentHireDate": { "type": "string", "description": "Date when a new agent can be hired next in ISO 8601 format (7 days after last hire)", "example": "2024-03-22T14:30:00Z", "nullable": true }, "firstReminderDelayDays": { "type": "number", "description": "Number of days to wait before sending the first reminder for an overdue invoice", "example": 3, "nullable": true }, "firstReminderDelayForDirectDebit": { "description": "Effective rule for an account collected by direct debit: its own override when one is set, otherwise firstReminderDelayDays read as that many days after the due date. Null when neither is set.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ReminderDelayResponseDto" } ] }, "firstReminderDelayForBankTransfer": { "description": "Same, for an account paying by bank transfer. An account whose payment method is unknown follows firstReminderDelayDays alone.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ReminderDelayResponseDto" } ] }, "minimumDunningAmount": { "type": "number", "description": "Amount below which an account is no longer reminded. Null means no floor.", "example": 5, "nullable": true }, "minimumDunningAmountCurrency": { "type": "string", "description": "Currency the floor above is expressed in. Null when there is no floor, and also on a legacy floor set before currencies existed: that one is read in each account own currency.", "example": "EUR", "nullable": true }, "credits": { "type": "number", "description": "Prepaid credits left for the channels that cost real money, SMS and postal letters. Emails never consume credits. Read-only: credits are topped up by Billabex.", "example": 250 }, "letterDetails": { "description": "What a postal reminder prints: the creditor identity and the account to pay into. A letter needs both the address and the IBAN; until they are there, postal reminders are refused before any credit is spent.", "allOf": [ { "$ref": "#/components/schemas/LetterDetailsResponseDto" } ] }, "logo": { "description": "Logo uploaded for this organization, or null. When null, a logo is derived from emailDomainName at display time and never stored.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/OrganizationLogoResponseDto" } ] } }, "required": [ "id", "name", "registrationDate", "emailDomainName", "memberIds", "invitations", "agents", "currentAgent", "lastAgentHiredDate", "nextAgentHireDate", "firstReminderDelayDays", "firstReminderDelayForDirectDebit", "firstReminderDelayForBankTransfer", "minimumDunningAmount", "minimumDunningAmountCurrency", "credits", "letterDetails", "logo" ] }, "public_api_dtos_responses_paginated_response_dto_PageInfoDto": { "type": "object", "properties": { "endCursor": { "type": "string", "description": "Cursor to use for fetching the next page", "example": "eyJpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCJ9" } } }, "PaginatedOrganizationsResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "description": "List of organizations", "type": "array", "items": { "$ref": "#/components/schemas/OrganizationResponseDto" } } }, "pageInfo": { "description": "Pagination info", "allOf": [ { "$ref": "#/components/schemas/public_api_dtos_responses_paginated_response_dto_PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "UpdateOrganizationInfoDto": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the organization", "example": "Acme Corporation Inc." }, "emailDomainName": { "type": "string", "description": "New email domain name for the organization (set to null to remove)", "example": "acme-corp.com", "nullable": true } } }, "UploadOrganizationLogoDto": { "type": "object", "properties": { "file": { "type": "string", "description": "Logo image (PNG, JPEG or WebP). The real file signature is checked, not the declared type: an SVG is refused. Maximum size: 2MB.", "format": "binary" } }, "required": [ "file" ] }, "ReminderDelayDto": { "type": "object", "properties": { "days": { "type": "number", "description": "Whole days between the due date and the first reminder, 0 to 365.", "example": 2 }, "direction": { "description": "Which side of the due date the reminder falls on. A direct debit is chased after it, a bank transfer announced before it.", "example": "AFTER", "allOf": [ { "$ref": "#/components/schemas/ReminderDelayDirection" } ] } }, "required": [ "days", "direction" ] }, "ISO4217Code": { "type": "string", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SPL", "SRD", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TVD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XCD", "XDR", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWD" ], "description": "Currency the floor above is expressed in, converted to each account currency at the rate of the day. Omit it to keep the currency already set, which is how an amount sent on its own has always behaved. Send it with the amount to change both, and send both as null to clear the floor." }, "SenderAddressDto": { "type": "object", "properties": { "street": { "type": "string", "description": "Street line of the creditor address", "example": "10 rue de Penthievre" }, "postalCode": { "type": "string", "description": "Postal code of the creditor address", "example": "75008" }, "city": { "type": "string", "description": "City of the creditor address", "example": "Paris" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code. Defaults to FR when omitted for backward compatibility.", "example": "FR" } }, "required": [ "street", "postalCode", "city" ] }, "LetterDetailsDto": { "type": "object", "properties": { "senderAddress": { "description": "Address the postal reminder is sent from. Send null to clear it.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/SenderAddressDto" } ] }, "siren": { "type": "string", "description": "French registration number of the creditor: nine digits, or a fourteen-digit SIRET of which only the first nine are kept. Send null to clear it.", "example": "123456789", "nullable": true }, "iban": { "type": "string", "description": "Account the debtor is asked to pay into. Validated against its own ISO 13616 check digits: a mistyped IBAN is refused rather than printed on a formal notice.", "example": "FR7630006000011234567890189", "nullable": true }, "bic": { "type": "string", "description": "BIC of the account above, 8 or 11 characters. Cannot be sent without an IBAN: on its own it names no account to pay into.", "example": "AGRIFRPP881", "nullable": true } } }, "UpdateOrganizationSettingsDto": { "type": "object", "properties": { "firstReminderDelayDays": { "type": "number", "description": "Number of days to wait before sending the first reminder for an overdue invoice. Set to null to remove.", "example": 3, "nullable": true }, "firstReminderDelayForDirectDebit": { "description": "When the first reminder becomes due for an account collected by direct debit, overriding firstReminderDelayDays for that mode. Set to null to record that this mode has no rule of its own and falls back on firstReminderDelayDays.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ReminderDelayDto" } ] }, "firstReminderDelayForBankTransfer": { "description": "Same rule for an account paying by bank transfer. An account whose payment method is unknown is governed by firstReminderDelayDays alone, never by either of these two.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ReminderDelayDto" } ] }, "minimumDunningAmount": { "type": "number", "description": "Inclusive floor: an account is still reminded when its balance equals this amount, and no longer when it is strictly below. A balance left by a conversion fee or a rounding is not worth chasing. Set to null to remove the floor.", "example": 5, "nullable": true }, "minimumDunningAmountCurrency": { "description": "Currency the floor above is expressed in, converted to each account currency at the rate of the day. Omit it to keep the currency already set, which is how an amount sent on its own has always behaved. Send it with the amount to change both, and send both as null to clear the floor.", "example": "EUR", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ISO4217Code" } ] }, "letterDetails": { "description": "What a postal reminder prints: the creditor identity and the account to pay into. Whole-object replace: send the four fields together, a field left out is cleared. Omit the key entirely to leave the block untouched.", "allOf": [ { "$ref": "#/components/schemas/LetterDetailsDto" } ] } } }, "CreateInvitationDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the person to invite", "example": "newmember@example.com", "format": "email" } }, "required": [ "email" ] }, "InvitationResponseDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address of the invited user", "example": "newmember@example.com", "format": "email" } }, "required": [ "email" ] }, "UserEmailResponseDto": { "type": "object", "properties": { "value": { "type": "string", "description": "Email address value", "example": "john.doe@example.com", "format": "email" }, "isVerified": { "type": "boolean", "description": "Whether the email address has been verified", "example": true } }, "required": [ "value", "isVerified" ] }, "UserAvatarResponseDto": { "type": "object", "properties": { "filestoreId": { "type": "string", "description": "Identifier of the stored file, downloadable at /api/file/{id}", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "filename": { "type": "string", "description": "Original filename of the uploaded picture", "example": "avatar.png" }, "uploadedAt": { "type": "string", "description": "Upload date in ISO 8601 format", "example": "2026-08-07T10:30:00Z" } }, "required": [ "filestoreId", "filename", "uploadedAt" ] }, "MemberResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the user (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "firstName": { "type": "string", "description": "First name of the user", "example": "John", "nullable": true }, "lastName": { "type": "string", "description": "Last name of the user", "example": "Doe", "nullable": true }, "fullName": { "type": "string", "description": "Full name of the user (computed from first and last name)", "example": "John Doe", "nullable": true }, "email": { "description": "Email information of the user", "allOf": [ { "$ref": "#/components/schemas/UserEmailResponseDto" } ] }, "language": { "type": "string", "description": "Language preference of the user (ISO 639-1 code)", "example": "en" }, "isActive": { "type": "boolean", "description": "Whether the user account is active (email verified)", "example": true }, "avatar": { "description": "Uploaded profile picture metadata", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/UserAvatarResponseDto" } ] } }, "required": [ "id", "firstName", "lastName", "fullName", "email", "language", "isActive", "avatar" ] }, "PredefinedTagCode": { "type": "string", "enum": [ "HumanFollowUp", "DisputeClaim", "PhoneCallRequest", "CollectiveProceedings", "WriteOff", "PaymentPromise", "CreditNoteRequest", "RecoveryAgencyTransfer", "NoDebtorResponse", "FinancialDifficulties", "DocumentRequest", "DebtorEmailError" ], "description": "Code of the predefined tag, null for custom tags" }, "TagResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the tag (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the owning organization, null for predefined tags", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid", "nullable": true }, "isPredefined": { "type": "boolean", "description": "Whether the tag is predefined and shared by all organizations", "example": false }, "code": { "description": "Code of the predefined tag, null for custom tags", "example": "PaymentPromise", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/PredefinedTagCode" } ] }, "name": { "type": "string", "description": "Display name of the tag, null for predefined tags", "example": "Key account", "nullable": true }, "color": { "type": "string", "description": "Color of the tag, hexadecimal code #RRGGBB, or a legacy named color for predefined tags", "example": "#2563eb" } }, "required": [ "id", "organizationId", "isPredefined", "code", "name", "color" ] }, "CreateTagDto": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the tag", "example": "Key account", "minLength": 1 }, "color": { "type": "string", "description": "Color of the tag, hexadecimal code #RRGGBB. Any non-empty string is accepted: the legacy named colors blue, red, green, purple, gray, teal, orange and pink are still used by predefined tags, any other name is rendered as gray.", "example": "#2563eb", "minLength": 1 } }, "required": [ "name", "color" ] }, "UploadUserAvatarDto": { "type": "object", "properties": { "file": { "type": "string", "description": "Profile picture (PNG, JPEG or WebP). The real file signature is checked. Maximum size: 2MB.", "format": "binary" } }, "required": [ "file" ] }, "AccountType": { "type": "string", "enum": [ "Professional", "Consumer", "Unknown" ], "description": "Nature of the account" }, "BodaccStatus": { "type": "string", "enum": [ "Unresolved", "Clear", "Receivership", "Liquidation", "Safeguard", "Dissolved" ], "description": "Latest BODACC classification, or null before the first successful check" }, "CurrencyResponseDto": { "type": "object", "properties": { "code": { "type": "string", "description": "ISO 4217 currency code", "example": "EUR" } }, "required": [ "code" ] }, "AccountPaymentMethod": { "type": "string", "enum": [ "DIRECT_DEBIT", "BANK_TRANSFER" ], "description": "How the account settles its invoices" }, "AddressResponseDto": { "type": "object", "properties": { "street": { "type": "string", "description": "Street address", "example": "123 Main Street", "nullable": true }, "city": { "type": "string", "description": "City name", "example": "Paris", "nullable": true }, "postalCode": { "type": "string", "description": "Postal or ZIP code", "example": "75001", "nullable": true }, "country": { "type": "string", "description": "Country code (ISO 3166-1 alpha-2)", "example": "FR", "nullable": true }, "stateOrProvince": { "type": "string", "description": "State or province name", "example": "Île-de-France", "nullable": true } }, "required": [ "street", "city", "postalCode", "country", "stateOrProvince" ] }, "ContactEmailResponseDto": { "type": "object", "properties": { "value": { "type": "string", "description": "Email address value", "example": "john.doe@example.com", "format": "email" }, "status": { "type": "string", "description": "Validation status of the email address", "enum": [ "Valid", "Bounced", "Complained" ], "example": "Valid" }, "isValid": { "type": "boolean", "description": "Whether the email address is valid for sending", "example": true } }, "required": [ "value", "status", "isValid" ] }, "ContactPhoneType": { "type": "string", "enum": [ "Mobile", "Landline", "Unknown" ], "description": "Derived from the number itself, never declared. Unknown covers the numbering plans that do not separate mobiles from landlines. Only a French Mobile can receive an SMS." }, "ContactPhoneOrigin": { "type": "string", "enum": [ "Manual", "Connector" ], "description": "Who put the number there. Connector numbers are owned by the sync and cannot be edited while the account is linked to its source." }, "ContactPhoneResponseDto": { "type": "object", "properties": { "number": { "type": "string", "description": "Phone number in E.164 format", "example": "+33612345678" }, "type": { "description": "Derived from the number itself, never declared. Unknown covers the numbering plans that do not separate mobiles from landlines. Only a French Mobile can receive an SMS.", "example": "Mobile", "allOf": [ { "$ref": "#/components/schemas/ContactPhoneType" } ] }, "country": { "type": "string", "description": "Country of the number (ISO 3166-1 alpha-2), derived from the number itself. Null when it belongs to no single country.", "example": "FR", "nullable": true }, "origin": { "description": "Who put the number there. Connector numbers are owned by the sync and cannot be edited while the account is linked to its source.", "example": "Manual", "allOf": [ { "$ref": "#/components/schemas/ContactPhoneOrigin" } ] } }, "required": [ "number", "type", "country", "origin" ] }, "ContactWriteWarningDto": { "type": "object", "properties": { "field": { "type": "string", "description": "Field of the contact that was not written", "enum": [ "fullName", "language", "phones" ], "example": "fullName" }, "value": { "type": "string", "description": "The value that was ignored, when naming it helps fix it", "example": "voir Jean" }, "reason": { "type": "string", "description": "Why it was ignored. MANUALLY_SET: the value was set by a person and this client declared itself an automated synchronization (`sync` scope). UNPARSEABLE: the phone number could not be normalized.", "enum": [ "MANUALLY_SET", "UNPARSEABLE" ], "example": "MANUALLY_SET" } }, "required": [ "field", "reason" ] }, "ContactResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the contact (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "fullName": { "type": "string", "description": "Full name of the contact", "example": "John Doe" }, "email": { "description": "Email information of the contact", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ContactEmailResponseDto" } ] }, "language": { "type": "string", "description": "Preferred language of the contact (ISO 639-1 code)", "example": "en" }, "jobTitle": { "type": "string", "description": "Role of the contact on the customer side, when known. Filled by contact enrichment or entered by a user.", "example": "Responsable comptabilité", "nullable": true }, "enabled": { "type": "boolean", "description": "Whether the contact is enabled. Disabled contacts are never proactively contacted by the AI agent.", "example": true }, "phones": { "description": "Every phone number of the contact, any country, whether typed by a user or brought by a connector.", "type": "array", "items": { "$ref": "#/components/schemas/ContactPhoneResponseDto" } }, "warnings": { "description": "What the write asked for and the API did not keep. Only on write responses, and omitted when everything was written.", "type": "array", "items": { "$ref": "#/components/schemas/ContactWriteWarningDto" } } }, "required": [ "id", "fullName", "email", "language", "jobTitle", "enabled", "phones" ] }, "SourceRefResponseDto": { "type": "object", "properties": { "connectionId": { "type": "string", "description": "Unique identifier of the connection (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "sourceId": { "type": "string", "description": "External source system identifier", "example": "EXT-12345" }, "connectorType": { "type": "string", "description": "Type of connector used for the source, including Qonto for Qonto-managed accounts", "enum": [ "Pennylane", "Qonto", "Sellsy", "Stripe", "ZohoBooks", "Custom" ], "example": "Qonto" }, "lastUpdate": { "type": "string", "description": "Last synchronization timestamp in ISO 8601 format", "example": "2024-01-15T10:30:00Z", "format": "date-time" } }, "required": [ "connectionId", "sourceId", "connectorType", "lastUpdate" ] }, "ReadOnlyReasonResponseDto": { "type": "object", "properties": { "connector": { "type": "string", "description": "The connector that owns this record. Its next synchronization would overwrite anything written here, so corrections belong in that tool.", "enum": [ "Pennylane", "Qonto", "Sellsy", "Stripe", "ZohoBooks", "Custom" ], "example": "Qonto" } }, "required": [ "connector" ] }, "AccountResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "fullName": { "type": "string", "description": "Full official name of the account or company", "example": "Acme Corporation" }, "accountType": { "description": "Nature of the account", "allOf": [ { "$ref": "#/components/schemas/AccountType" } ] }, "bodaccStatus": { "description": "Latest BODACC classification, or null before the first successful check", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/BodaccStatus" } ] }, "bodaccCheckedAt": { "type": "string", "description": "Timestamp of the latest successful BODACC check in ISO 8601 format", "example": "2026-08-14T10:30:00.000Z", "format": "date-time", "nullable": true }, "siren": { "type": "object", "description": "Normalized French SIREN", "example": "123456789", "nullable": true }, "vatNumber": { "type": "object", "description": "Normalized EU VAT identification number", "example": "FR40123456789", "nullable": true }, "currency": { "description": "Currency used for this account", "allOf": [ { "$ref": "#/components/schemas/CurrencyResponseDto" } ] }, "paymentMethod": { "description": "How the account settles its invoices", "example": "DIRECT_DEBIT", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AccountPaymentMethod" } ] }, "domain": { "type": "string", "description": "Bare domain stated for the account's company, normalized (lowercase, no scheme, no leading www., no port, no path). Null when nobody stated one. Filled by the Sellsy and Zoho Books syncs from the customer's website; Pennylane, Qonto and Stripe carry no such field.", "example": "acme.com", "nullable": true }, "reference": { "type": "string", "description": "Free-text reference the organization uses for this customer in its own tools: a customer code, an accounting code, a trade name. Null when nobody stated one. Filled by the Pennylane, Sellsy and Zoho Books syncs when the customer carries one; Qonto and Stripe have no such field.", "example": "CLI-1654", "nullable": true }, "logoDomain": { "type": "string", "description": "Domain a logo can be fetched from: `domain` when set, otherwise the sole unambiguous contact domain after accounting for the organization's own email domain. The organization domain remains valid when every contact uses it. Null when no safe choice exists. Read-only, nothing is stored.", "example": "acme.com", "nullable": true }, "billingAddress": { "description": "Primary billing address for the account", "allOf": [ { "$ref": "#/components/schemas/AddressResponseDto" } ] }, "contacts": { "type": "array", "items": { "description": "List of external contacts associated with the account", "type": "array", "items": { "$ref": "#/components/schemas/ContactResponseDto" } } }, "hasValidEmailContact": { "type": "boolean", "description": "Whether the account has at least one contact with a valid email address", "example": true }, "hasValidPhoneContact": { "type": "boolean", "description": "Whether the account has at least one enabled contact with a mobile phone number", "example": true }, "source": { "description": "Reference to the external source system if the account was imported from Pennylane, Qonto, Sellsy, Stripe, Zoho Books, or a custom API integration", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/SourceRefResponseDto" } ] }, "lastUnlinkedSource": { "description": "Reference to the external source system this account was detached from, null if it never had one. Read together with `source`: both null means the account was created by hand or through this API, this one set alone means the connector link was broken and the account no longer follows the billing tool", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/SourceRefResponseDto" } ] }, "tagIds": { "description": "Identifiers of the tags attached to the account (see GET /organizations/{organizationId}/tags)", "example": [ "123e4567-e89b-12d3-a456-426614174000" ], "type": "array", "items": { "type": "string", "format": "uuid" } }, "readOnlyReason": { "description": "Why this account refuses writes, or null when it accepts them. Set while a connector still syncs the account, since its next run would overwrite anything written here. A `Custom` source does not lock: it is this API driving itself. A write attempted while this is set fails with app-invoicing.account.managed-action-forbidden, whose `details` repeats it.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ReadOnlyReasonResponseDto" } ] } }, "required": [ "id", "organizationId", "fullName", "accountType", "bodaccStatus", "bodaccCheckedAt", "siren", "vatNumber", "currency", "paymentMethod", "domain", "reference", "logoDomain", "billingAddress", "contacts", "hasValidEmailContact", "hasValidPhoneContact", "source", "lastUnlinkedSource", "tagIds", "readOnlyReason" ] }, "dtos_responses_paginated_response_dto_PageInfoDto": { "type": "object", "properties": { "endCursor": { "type": "string", "description": "Cursor to use for fetching the next page", "example": "eyJpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCJ9" } } }, "PaginatedAccountsResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "description": "List of accounts", "type": "array", "items": { "$ref": "#/components/schemas/AccountResponseDto" } } }, "pageInfo": { "description": "Pagination info", "allOf": [ { "$ref": "#/components/schemas/dtos_responses_paginated_response_dto_PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "AddressDto": { "type": "object", "properties": { "street": { "type": "object", "description": "Street address line (building number, street name)", "example": "123 Main Street", "nullable": true }, "city": { "type": "object", "description": "City or town name", "example": "Paris", "nullable": true }, "postalCode": { "type": "object", "description": "Postal or ZIP code", "example": "75001", "nullable": true }, "stateOrProvince": { "type": "object", "description": "State, province, or region name", "example": "Ile-de-France", "nullable": true }, "country": { "type": "object", "description": "Country name or ISO 3166-1 code", "example": "France", "nullable": true } } }, "CreateSourceRefDto": { "type": "object", "properties": { "connectionId": { "type": "string", "description": "Unique identifier for the connection/integration in your system. This is a free-form identifier you choose to group accounts from the same source.", "example": "my-erp-integration-123" }, "sourceId": { "type": "string", "description": "External source system identifier. This is the unique identifier of the account in your external system.", "example": "CUST-00123" }, "lastUpdate": { "type": "string", "description": "Last synchronization date. If not provided, defaults to the current date/time.", "example": "2024-01-15T10:30:00.000Z", "format": "date-time" } }, "required": [ "connectionId", "sourceId" ] }, "CreateAccountDto": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "fullName": { "type": "string", "description": "Official name of the account or company", "example": "Acme Corporation", "minLength": 1 }, "accountType": { "description": "Nature of the account. Omit it to infer Professional from a legal identifier, otherwise Unknown.", "allOf": [ { "$ref": "#/components/schemas/AccountType" } ] }, "siren": { "type": "string", "description": "French SIREN (9 digits) or SIRET (14 digits)", "example": "123456789" }, "vatNumber": { "type": "string", "description": "EU VAT identification number", "example": "FR40123456789" }, "domain": { "type": "string", "description": "Website or bare host of the account's company. Stored as a bare domain: the scheme, a leading www., a port and any path are stripped, and the result is lowercased. Used to fetch a logo and to target contact enrichment.", "example": "acme.com" }, "reference": { "type": "string", "description": "Free-text reference the organization uses for this customer in its own tools: a customer code, an accounting code, a trade name. Stored trimmed, never parsed. Filled by the Pennylane, Sellsy and Zoho Books syncs when the customer carries one; Qonto and Stripe have no such field.", "example": "CLI-1654", "maxLength": 200 }, "currencyCode": { "description": "ISO 4217 currency code for account transactions", "example": "EUR", "allOf": [ { "$ref": "#/components/schemas/ISO4217Code" } ] }, "billingAddress": { "description": "Primary billing address for the account", "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ] }, "contacts": { "description": "List of external contacts associated with the account", "default": [], "items": { "type": "array", "items": { "type": "createContactDto" } }, "type": "array" }, "source": { "description": "Optional custom source reference linking this account to an external system. When provided, the account is managed via API and cannot be excluded via the UI.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/CreateSourceRefDto" } ] } }, "required": [ "organizationId", "fullName", "currencyCode", "billingAddress", "contacts" ] }, "date_value_response_dto_DateValueResponseDto": { "type": "object", "properties": { "year": { "type": "number", "description": "Year component of the date", "example": 2024 }, "month": { "type": "number", "description": "Month component of the date (1-12)", "example": 12, "minimum": 1, "maximum": 12 }, "day": { "type": "number", "description": "Day component of the date (1-31)", "example": 31, "minimum": 1, "maximum": 31 } }, "required": [ "year", "month", "day" ] }, "AccountInvoiceInstallmentResponseDto": { "type": "object", "properties": { "invoiceId": { "type": "string", "format": "uuid" }, "invoiceNumber": { "type": "string", "example": "INV-2026-001" }, "dueDate": { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" }, "scheduledAmount": { "type": "number", "example": 500 }, "remainingAmount": { "type": "number", "example": 250 }, "position": { "type": "number", "example": 1 }, "count": { "type": "number", "example": 3 } }, "required": [ "invoiceId", "invoiceNumber", "dueDate", "scheduledAmount", "remainingAmount", "position", "count" ] }, "AccountOperationalBalanceResponseDto": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "referenceDate": { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" }, "invoiceBalance": { "type": "number", "description": "Sum of invoice remaining balances" }, "creditNoteBalance": { "type": "number", "description": "Sum of unallocated credit note balances" }, "balance": { "type": "number", "description": "Invoice balance minus credit note balance" }, "overdueBalance": { "type": "number", "description": "Amount still due on installments reaching their due date on or before the reference date" }, "overdueInvoiceCount": { "type": "number", "description": "Number of invoices contributing to the overdue balance" }, "installments": { "type": "array", "items": { "$ref": "#/components/schemas/AccountInvoiceInstallmentResponseDto" } } }, "required": [ "accountId", "referenceDate", "invoiceBalance", "creditNoteBalance", "balance", "overdueBalance", "overdueInvoiceCount", "installments" ] }, "UpdateAccountDto": { "type": "object", "properties": { "accountType": { "description": "Nature of the account", "allOf": [ { "$ref": "#/components/schemas/AccountType" } ] }, "fullName": { "type": "string", "description": "Official name of the account or company", "example": "Acme Corporation" }, "siren": { "type": "string", "description": "French SIREN (9 digits) or SIRET (14 digits)", "example": "123456789" }, "vatNumber": { "type": "string", "description": "EU VAT identification number", "example": "FR40123456789" }, "domain": { "type": "object", "description": "Website or bare host of the account's company. Stored as a bare domain: the scheme, a leading www., a port and any path are stripped, and the result is lowercased. Used to fetch a logo and to target contact enrichment. Null clears it.", "example": "acme.com", "nullable": true }, "reference": { "type": "object", "description": "Free-text reference the organization uses for this customer in its own tools: a customer code, an accounting code, a trade name. Stored trimmed, never parsed. Null clears it. Refused on an account a connector still syncs, which would overwrite it.", "example": "CLI-1654", "nullable": true, "maxLength": 200 }, "currencyCode": { "description": "ISO 4217 currency code for account transactions", "example": "EUR", "allOf": [ { "$ref": "#/components/schemas/ISO4217Code" } ] }, "billingAddress": { "description": "Primary billing address for the account", "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ] }, "paymentMethod": { "description": "How the account settles its invoices. Decides when the first reminder becomes due and whether the bank details are attached to it. Null clears the setting, which is not the same as a bank transfer: an account nobody configured keeps the organization-wide cadence.", "example": "DIRECT_DEBIT", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AccountPaymentMethod" } ] } } }, "UpdateSourceRefDto": { "type": "object", "properties": { "lastUpdate": { "type": "string", "description": "Last synchronization date. If not provided, defaults to the current date/time.", "example": "2024-01-15T10:30:00.000Z", "format": "date-time" } } }, "AssignAccountTagsDto": { "type": "object", "properties": { "tagIds": { "description": "Identifiers of the tags to attach, obtained from GET /organizations/{organizationId}/tags", "example": [ "123e4567-e89b-12d3-a456-426614174000" ], "minItems": 1, "maxItems": 25, "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "tagIds" ] }, "ISO639_1Code": { "type": "string", "enum": [ "aa", "ab", "af", "ak", "am", "ar", "as", "ay", "az", "ba", "be", "bg", "bh", "bi", "bn", "bo", "br", "ca", "co", "cs", "cy", "da", "de", "dz", "el", "en", "eo", "es", "et", "eu", "fa", "fi", "fj", "fo", "fr", "fy", "ga", "gd", "gl", "gn", "gu", "ha", "he", "hi", "hr", "hu", "hy", "ia", "id", "ie", "ig", "ik", "is", "it", "iu", "ja", "jv", "ka", "kk", "kl", "km", "kn", "ko", "ks", "ku", "ky", "la", "ln", "lo", "lt", "lv", "mg", "mi", "mk", "ml", "mn", "mo", "mr", "ms", "mt", "my", "na", "ne", "nl", "no", "oc", "om", "or", "pa", "pl", "ps", "pt", "qu", "rm", "rn", "ro", "ru", "rw", "sa", "sd", "sg", "sh", "si", "sk", "sl", "sm", "sn", "so", "sq", "sr", "ss", "st", "su", "sv", "sw", "ta", "te", "tg", "th", "ti", "tk", "tl", "tn", "to", "tr", "ts", "tt", "tw", "ug", "uk", "ur", "uz", "vi", "vo", "wo", "xh", "yi", "yo", "za", "zh", "zu" ], "description": "Preferred language code (ISO 639-1)" }, "ContactPhoneDto": { "type": "object", "properties": { "number": { "type": "string", "description": "Phone number. International form (starting with + or 00) is taken as-is; a national number needs countryCode alongside it.", "example": "+33612345678" }, "countryCode": { "type": "object", "description": "Country of the number (ISO 3166-1 alpha-2). Required unless the number starts with + or 00. There is no default: guessing a country silently rewrites the number into a different one.", "example": "FR", "nullable": true } }, "required": [ "number" ] }, "CreateContactDto": { "type": "object", "properties": { "fullName": { "type": "string", "description": "Full name of the contact", "example": "John Doe", "minLength": 1 }, "email": { "type": "object", "description": "Contact email address", "example": "john.doe@example.com", "nullable": true, "format": "email" }, "language": { "description": "Preferred language code (ISO 639-1)", "example": "en", "allOf": [ { "$ref": "#/components/schemas/ISO639_1Code" } ] }, "jobTitle": { "type": "object", "description": "Role of the contact on the customer side, free text. Sending null clears it.", "example": "Responsable comptabilité", "nullable": true }, "phones": { "description": "Every phone number of the contact, any country. The list is authoritative: omit it to leave the numbers alone, send an empty array to clear them. Numbers a connector brought are never replaced from here.", "type": "array", "items": { "$ref": "#/components/schemas/ContactPhoneDto" } } }, "required": [ "fullName", "language" ] }, "UpdateContactDto": { "type": "object", "properties": { "fullName": { "type": "string", "description": "Full name of the contact", "example": "John Doe" }, "email": { "type": "object", "description": "Contact email address", "example": "john.doe@example.com", "nullable": true, "format": "email" }, "language": { "description": "Preferred language code (ISO 639-1)", "example": "en", "allOf": [ { "$ref": "#/components/schemas/ISO639_1Code" } ] }, "jobTitle": { "type": "object", "description": "Role of the contact on the customer side, free text. Sending null clears it.", "example": "Responsable comptabilité", "nullable": true }, "phones": { "description": "Every phone number of the contact, any country. The list is authoritative: omit it to leave the numbers alone, send an empty array to clear them. Numbers a connector brought are never replaced from here.", "type": "array", "items": { "$ref": "#/components/schemas/ContactPhoneDto" } } } }, "SetContactEnabledDto": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Whether the contact is enabled. Disabled contacts are never proactively contacted by the AI agent.", "example": false } }, "required": [ "enabled" ] }, "ContactCandidateResponseDto": { "type": "object", "properties": { "fullName": { "type": "string", "description": "Full name of the person", "example": "Marie Dupont" }, "jobTitle": { "type": "string", "description": "Role of the person on the customer side", "example": "Responsable comptabilité", "nullable": true }, "companyName": { "type": "string", "description": "Company the person currently works for", "example": "ACME SAS", "nullable": true }, "profileUrl": { "type": "string", "description": "Public professional profile URL. Pass it back to the enrichment endpoint: it is the strongest input the provider can be given.", "example": "https://www.linkedin.com/in/marie-dupont", "nullable": true } }, "required": [ "fullName", "jobTitle", "companyName", "profileUrl" ] }, "ContactEmailKind": { "type": "string", "enum": [ "Professional", "Personal" ], "description": "Kind of email address to look for: a work one for a company, a personal one for an individual." }, "EnrichContactDto": { "type": "object", "properties": { "contactId": { "type": "string", "description": "Contact to complete, when it already exists but lacks an address or a number. Omit to add a new contact from the search.", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "fullName": { "type": "string", "description": "Who to look for. Required unless a contactId or a profileUrl identifies the person.", "example": "Marie Dupont" }, "profileUrl": { "type": "string", "description": "Public professional profile URL, typically taken from the candidate search. The strongest input the provider can be given.", "example": "https://www.linkedin.com/in/marie-dupont" }, "jobTitle": { "type": "string", "description": "Role of the person, when known from the candidate search.", "example": "Responsable comptabilité" }, "emailKind": { "description": "Kind of email address to look for: a work one for a company, a personal one for an individual.", "example": "Professional", "allOf": [ { "$ref": "#/components/schemas/ContactEmailKind" } ] }, "wantsPhone": { "type": "boolean", "description": "Also look for a phone number. Costs 2 credits instead of 1, and only if a number is found.", "example": false } }, "required": [ "emailKind", "wantsPhone" ] }, "ContactEnrichmentResponseDto": { "type": "object", "properties": { "enrichmentId": { "type": "string", "description": "Identifier of the started enrichment. The contact appears on the account about a minute later, on its own; nothing has to be polled.", "example": "2db5ea61-1752-42cf-8ea1-ab1da060cd0a" } }, "required": [ "enrichmentId" ] }, "UpsertContactDto": { "type": "object", "properties": { "fullName": { "type": "string", "description": "Full name of the contact. Required when creating a new contact.", "example": "John Doe" }, "email": { "type": "object", "description": "Contact email address. Used for matching existing contacts. Required when creating a new contact.", "example": "john.doe@example.com", "nullable": true, "format": "email" }, "language": { "description": "Preferred language code (ISO 639-1). Required when creating a new contact.", "example": "en", "allOf": [ { "$ref": "#/components/schemas/ISO639_1Code" } ] }, "jobTitle": { "type": "object", "description": "Role of the contact on the customer side, free text. Sending null clears it.", "example": "Responsable comptabilité", "nullable": true }, "phones": { "description": "Every phone number of the contact, any country. The list is authoritative: omit it to leave the numbers alone, send an empty array to clear them. Numbers a connector brought are never replaced from here.", "type": "array", "items": { "$ref": "#/components/schemas/ContactPhoneDto" } } } }, "PaymentInstallmentResponseDto": { "type": "object", "properties": { "dueDate": { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" }, "amount": { "type": "number", "example": 500 } }, "required": [ "dueDate", "amount" ] }, "CreditAllocationResponseDto": { "type": "object", "properties": { "invoiceId": { "type": "string", "description": "Unique identifier of the invoice (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "amount": { "type": "number", "description": "Amount allocated from the credit note to the invoice", "example": 100 }, "creditNoteId": { "type": "string", "description": "Unique identifier of the credit note (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" } }, "required": [ "invoiceId", "amount", "creditNoteId" ] }, "InvoiceListItemResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the invoice (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "number": { "type": "string", "description": "Invoice number", "example": "INV-2024-001" }, "issuedDate": { "description": "Date when the invoice was issued", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "dueDate": { "description": "Payment due date", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "effectiveDueDate": { "description": "Next operational due date after applying the payment schedule and existing payments or credits", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "paymentSchedule": { "type": "array", "items": { "description": "Complete payment schedule, empty when none is configured", "type": "array", "items": { "$ref": "#/components/schemas/PaymentInstallmentResponseDto" } } }, "totalAmount": { "type": "number", "description": "Total amount including taxes", "example": 1200 }, "taxAmount": { "type": "number", "description": "Tax amount included in total", "example": 200 }, "paidAmount": { "type": "number", "description": "Amount already paid", "example": 500 }, "paidDate": { "description": "Date when the invoice was fully paid", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "creditAllocations": { "type": "array", "items": { "description": "List of credit allocations applied to this invoice", "type": "array", "items": { "$ref": "#/components/schemas/CreditAllocationResponseDto" } } }, "poNumber": { "type": "string", "description": "Purchase order number reference", "example": "PO-2024-001", "nullable": true }, "billingAddress": { "description": "Billing address for this invoice", "allOf": [ { "$ref": "#/components/schemas/AddressResponseDto" } ] }, "creditAmount": { "type": "number", "description": "Total amount of credits allocated to this invoice", "example": 100 }, "remainingBalance": { "type": "number", "description": "Remaining balance after payments and credits", "example": 600 }, "paymentStatus": { "type": "string", "description": "Payment status of the invoice", "enum": [ "Unpaid", "PartiallyPaid", "Paid", "Overpaid" ], "example": "PartiallyPaid" }, "status": { "type": "string", "description": "Current status of the invoice", "enum": [ "Issued", "Paid", "Overdue" ], "example": "Issued" }, "filestoreId": { "type": "string", "description": "Unique identifier of the stored invoice file (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174003", "format": "uuid" }, "channel": { "type": "string", "description": "Channel through which the invoice was issued", "enum": [ "Pennylane", "Qonto", "Sellsy", "Stripe", "ZohoBooks", "Api", "PublicApi", "AdminApi", "Mcp", "Manual" ], "example": "Manual" }, "connectionId": { "type": "string", "description": "The connection that issued this invoice, or null when no connector did. Frozen at issuance, and never set by a public API call.", "example": "123e4567-e89b-12d3-a456-426614174004", "format": "uuid", "nullable": true }, "sourceId": { "type": "string", "description": "Your own identifier for this invoice in the system it comes from, as sent at creation. Unique within the organization, frozen at issuance.", "example": "netsuite:invoice:184920", "nullable": true }, "readOnlyReason": { "description": "Why this invoice refuses writes, or null when it accepts them. Do not derive this from `channel`: a connector-issued invoice becomes writable again once its account is unlinked. An update or delete attempted while this is set fails with app-invoicing.document.managed-action-forbidden, whose `details` repeats it.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ReadOnlyReasonResponseDto" } ] }, "accountPaymentMethod": { "description": "How the invoice's account settles its invoices", "example": "DIRECT_DEBIT", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AccountPaymentMethod" } ] } }, "required": [ "id", "organizationId", "accountId", "number", "issuedDate", "dueDate", "effectiveDueDate", "paymentSchedule", "totalAmount", "taxAmount", "paidAmount", "paidDate", "creditAllocations", "poNumber", "billingAddress", "creditAmount", "remainingBalance", "paymentStatus", "status", "filestoreId", "channel", "connectionId", "sourceId", "readOnlyReason", "accountPaymentMethod" ] }, "PaginatedInvoicesResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "description": "List of invoices", "type": "array", "items": { "$ref": "#/components/schemas/InvoiceListItemResponseDto" } } }, "pageInfo": { "description": "Pagination info", "allOf": [ { "$ref": "#/components/schemas/dtos_responses_paginated_response_dto_PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "DateValueDto": { "type": "object", "properties": { "year": { "type": "number", "description": "Year (4-digit format)", "example": 2024, "minimum": 1900, "maximum": 2100 }, "month": { "type": "number", "description": "Month (1-12)", "example": 6, "minimum": 1, "maximum": 12 }, "day": { "type": "number", "description": "Day of month (1-31)", "example": 15, "minimum": 1, "maximum": 31 } }, "required": [ "year", "month", "day" ] }, "CreateInvoiceDto": { "type": "object", "properties": { "accountId": { "type": "string", "description": "Account ID that this invoice belongs to (UUID v4)", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "number": { "type": "string", "description": "Unique invoice number within the organization", "example": "INV-2024-001" }, "issuedDate": { "description": "Date when the invoice was issued", "allOf": [ { "$ref": "#/components/schemas/DateValueDto" } ] }, "dueDate": { "description": "Payment due date", "allOf": [ { "$ref": "#/components/schemas/DateValueDto" } ] }, "totalAmount": { "type": "number", "description": "Total amount including taxes", "example": 1200, "minimum": 0 }, "taxAmount": { "type": "number", "description": "Tax amount included in total", "example": 200, "minimum": 0 }, "paidAmount": { "type": "number", "description": "Amount already paid", "example": 0, "minimum": 0, "default": 0 }, "poNumber": { "type": "object", "description": "Purchase order number reference", "example": "PO-2024-001", "nullable": true }, "sourceId": { "type": "object", "description": "Your own identifier for this invoice in the system it comes from. Unique within the organization and frozen at issuance: re-sending an already used value is refused with app-invoicing.invoice.duplicate-source-id, so a retry after a lost response cannot create a duplicate.", "example": "netsuite:invoice:184920", "nullable": true }, "billingAddress": { "description": "Billing address for this invoice", "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ] }, "file": { "type": "string", "description": "Invoice document file (PDF or image). Supports binary upload (default) or base64 encoding. For base64, set Content-Transfer-Encoding: base64 in the file part header. Maximum size: 10MB (decoded binary size).", "format": "binary" } }, "required": [ "accountId", "number", "issuedDate", "dueDate", "totalAmount", "taxAmount", "paidAmount", "billingAddress", "file" ] }, "InvoiceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the invoice (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "number": { "type": "string", "description": "Invoice number", "example": "INV-2024-001" }, "issuedDate": { "description": "Date when the invoice was issued", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "dueDate": { "description": "Payment due date", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "effectiveDueDate": { "description": "Next operational due date after applying the payment schedule and existing payments or credits", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "paymentSchedule": { "type": "array", "items": { "description": "Complete payment schedule, empty when none is configured", "type": "array", "items": { "$ref": "#/components/schemas/PaymentInstallmentResponseDto" } } }, "totalAmount": { "type": "number", "description": "Total amount including taxes", "example": 1200 }, "taxAmount": { "type": "number", "description": "Tax amount included in total", "example": 200 }, "paidAmount": { "type": "number", "description": "Amount already paid", "example": 500 }, "paidDate": { "description": "Date when the invoice was fully paid", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "creditAllocations": { "type": "array", "items": { "description": "List of credit allocations applied to this invoice", "type": "array", "items": { "$ref": "#/components/schemas/CreditAllocationResponseDto" } } }, "poNumber": { "type": "string", "description": "Purchase order number reference", "example": "PO-2024-001", "nullable": true }, "billingAddress": { "description": "Billing address for this invoice", "allOf": [ { "$ref": "#/components/schemas/AddressResponseDto" } ] }, "creditAmount": { "type": "number", "description": "Total amount of credits allocated to this invoice", "example": 100 }, "remainingBalance": { "type": "number", "description": "Remaining balance after payments and credits", "example": 600 }, "paymentStatus": { "type": "string", "description": "Payment status of the invoice", "enum": [ "Unpaid", "PartiallyPaid", "Paid", "Overpaid" ], "example": "PartiallyPaid" }, "status": { "type": "string", "description": "Current status of the invoice", "enum": [ "Issued", "Paid", "Overdue" ], "example": "Issued" }, "filestoreId": { "type": "string", "description": "Unique identifier of the stored invoice file (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174003", "format": "uuid" }, "channel": { "type": "string", "description": "Channel through which the invoice was issued", "enum": [ "Pennylane", "Qonto", "Sellsy", "Stripe", "ZohoBooks", "Api", "PublicApi", "AdminApi", "Mcp", "Manual" ], "example": "Manual" }, "connectionId": { "type": "string", "description": "The connection that issued this invoice, or null when no connector did. Frozen at issuance, and never set by a public API call.", "example": "123e4567-e89b-12d3-a456-426614174004", "format": "uuid", "nullable": true }, "sourceId": { "type": "string", "description": "Your own identifier for this invoice in the system it comes from, as sent at creation. Unique within the organization, frozen at issuance.", "example": "netsuite:invoice:184920", "nullable": true } }, "required": [ "id", "organizationId", "accountId", "number", "issuedDate", "dueDate", "effectiveDueDate", "paymentSchedule", "totalAmount", "taxAmount", "paidAmount", "paidDate", "creditAllocations", "poNumber", "billingAddress", "creditAmount", "remainingBalance", "paymentStatus", "status", "filestoreId", "channel", "connectionId", "sourceId" ] }, "InvoiceDetailResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the invoice (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "number": { "type": "string", "description": "Invoice number", "example": "INV-2024-001" }, "issuedDate": { "description": "Date when the invoice was issued", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "dueDate": { "description": "Payment due date", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "effectiveDueDate": { "description": "Next operational due date after applying the payment schedule and existing payments or credits", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "paymentSchedule": { "type": "array", "items": { "description": "Complete payment schedule, empty when none is configured", "type": "array", "items": { "$ref": "#/components/schemas/PaymentInstallmentResponseDto" } } }, "totalAmount": { "type": "number", "description": "Total amount including taxes", "example": 1200 }, "taxAmount": { "type": "number", "description": "Tax amount included in total", "example": 200 }, "paidAmount": { "type": "number", "description": "Amount already paid", "example": 500 }, "paidDate": { "description": "Date when the invoice was fully paid", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "creditAllocations": { "type": "array", "items": { "description": "List of credit allocations applied to this invoice", "type": "array", "items": { "$ref": "#/components/schemas/CreditAllocationResponseDto" } } }, "poNumber": { "type": "string", "description": "Purchase order number reference", "example": "PO-2024-001", "nullable": true }, "billingAddress": { "description": "Billing address for this invoice", "allOf": [ { "$ref": "#/components/schemas/AddressResponseDto" } ] }, "creditAmount": { "type": "number", "description": "Total amount of credits allocated to this invoice", "example": 100 }, "remainingBalance": { "type": "number", "description": "Remaining balance after payments and credits", "example": 600 }, "paymentStatus": { "type": "string", "description": "Payment status of the invoice", "enum": [ "Unpaid", "PartiallyPaid", "Paid", "Overpaid" ], "example": "PartiallyPaid" }, "status": { "type": "string", "description": "Current status of the invoice", "enum": [ "Issued", "Paid", "Overdue" ], "example": "Issued" }, "filestoreId": { "type": "string", "description": "Unique identifier of the stored invoice file (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174003", "format": "uuid" }, "channel": { "type": "string", "description": "Channel through which the invoice was issued", "enum": [ "Pennylane", "Qonto", "Sellsy", "Stripe", "ZohoBooks", "Api", "PublicApi", "AdminApi", "Mcp", "Manual" ], "example": "Manual" }, "connectionId": { "type": "string", "description": "The connection that issued this invoice, or null when no connector did. Frozen at issuance, and never set by a public API call.", "example": "123e4567-e89b-12d3-a456-426614174004", "format": "uuid", "nullable": true }, "sourceId": { "type": "string", "description": "Your own identifier for this invoice in the system it comes from, as sent at creation. Unique within the organization, frozen at issuance.", "example": "netsuite:invoice:184920", "nullable": true }, "readOnlyReason": { "description": "Why this invoice refuses writes, or null when it accepts them. Do not derive this from `channel`: a connector-issued invoice becomes writable again once its account is unlinked. An update or delete attempted while this is set fails with app-invoicing.document.managed-action-forbidden, whose `details` repeats it.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ReadOnlyReasonResponseDto" } ] } }, "required": [ "id", "organizationId", "accountId", "number", "issuedDate", "dueDate", "effectiveDueDate", "paymentSchedule", "totalAmount", "taxAmount", "paidAmount", "paidDate", "creditAllocations", "poNumber", "billingAddress", "creditAmount", "remainingBalance", "paymentStatus", "status", "filestoreId", "channel", "connectionId", "sourceId", "readOnlyReason" ] }, "SetInvoicePaidAmountDto": { "type": "object", "properties": { "paidAmount": { "type": "number", "description": "New paid amount for the invoice", "example": 500, "minimum": 0 } }, "required": [ "paidAmount" ] }, "PaymentInstallmentDto": { "type": "object", "properties": { "dueDate": { "$ref": "#/components/schemas/DateValueDto" }, "amount": { "type": "number", "example": 500, "minimum": 0, "exclusiveMinimum": true } }, "required": [ "dueDate", "amount" ] }, "SetInvoicePaymentScheduleDto": { "type": "object", "properties": { "installments": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentInstallmentDto" } } } }, "required": [ "installments" ] }, "CreditNoteListItemResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the credit note (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "number": { "type": "string", "description": "Credit note number", "example": "CN-2024-001" }, "issuedDate": { "description": "Date when the credit note was issued", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "totalAmount": { "type": "number", "description": "Total amount of the credit note including taxes", "example": 500 }, "taxAmount": { "type": "number", "description": "Tax amount included in total", "example": 83.33 }, "creditAllocations": { "type": "array", "items": { "description": "List of credit allocations from this credit note to invoices", "type": "array", "items": { "$ref": "#/components/schemas/CreditAllocationResponseDto" } } }, "billingAddress": { "description": "Billing address for this credit note", "allOf": [ { "$ref": "#/components/schemas/AddressResponseDto" } ] }, "creditAmount": { "type": "number", "description": "Total amount of credits allocated from this credit note", "example": 200 }, "refundedAmount": { "type": "number", "description": "Total refunded amount (cash refunds)", "example": 50 }, "remainingAmount": { "type": "number", "description": "Remaining amount available for allocation", "example": 300 }, "status": { "type": "string", "description": "Current status of the credit note", "enum": [ "Issued", "PartiallySettled", "Settled" ], "example": "PartiallySettled" }, "filestoreId": { "type": "string", "description": "Unique identifier of the stored credit note file (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174003", "format": "uuid" }, "channel": { "type": "string", "description": "Channel through which the credit note was issued", "enum": [ "Pennylane", "Qonto", "Sellsy", "Stripe", "ZohoBooks", "Api", "PublicApi", "AdminApi", "Mcp", "Manual" ], "example": "Manual" }, "connectionId": { "type": "string", "description": "The connection that issued this credit note, or null when no connector did. Frozen at issuance, and never set by a public API call.", "example": "123e4567-e89b-12d3-a456-426614174004", "format": "uuid", "nullable": true }, "sourceId": { "type": "string", "description": "Your own identifier for this credit note in the system it comes from, as sent at creation. Unique within the organization, frozen at issuance.", "example": "netsuite:creditmemo:184921", "nullable": true }, "readOnlyReason": { "description": "Why this credit note refuses writes, or null when it accepts them. Do not derive this from `channel`: a connector-issued credit note becomes writable again once its account is unlinked. A delete attempted while this is set fails with app-invoicing.document.managed-action-forbidden, whose `details` repeats it.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ReadOnlyReasonResponseDto" } ] }, "accountPaymentMethod": { "description": "How the credit note's account settles its invoices", "example": "DIRECT_DEBIT", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/AccountPaymentMethod" } ] } }, "required": [ "id", "organizationId", "accountId", "number", "issuedDate", "totalAmount", "taxAmount", "creditAllocations", "billingAddress", "creditAmount", "refundedAmount", "remainingAmount", "status", "filestoreId", "channel", "connectionId", "sourceId", "readOnlyReason", "accountPaymentMethod" ] }, "PaginatedCreditNotesResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "description": "List of credit notes", "type": "array", "items": { "$ref": "#/components/schemas/CreditNoteListItemResponseDto" } } }, "pageInfo": { "description": "Pagination info", "allOf": [ { "$ref": "#/components/schemas/dtos_responses_paginated_response_dto_PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "CreateCreditNoteDto": { "type": "object", "properties": { "accountId": { "type": "string", "description": "Account ID that this credit note belongs to (UUID v4)", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "number": { "type": "string", "description": "Unique credit note number within the organization", "example": "CN-2024-001" }, "issuedDate": { "description": "Date when the credit note was issued", "allOf": [ { "$ref": "#/components/schemas/DateValueDto" } ] }, "totalAmount": { "type": "number", "description": "Total credit amount including taxes", "example": 500, "minimum": 0 }, "taxAmount": { "type": "number", "description": "Tax amount included in total", "example": 83.33, "minimum": 0 }, "sourceId": { "type": "object", "description": "Your own identifier for this credit note in the system it comes from. Unique within the organization and frozen at issuance: re-sending an already used value is refused with app-invoicing.credit-note.duplicate-source-id, so a retry after a lost response cannot create a duplicate.", "example": "netsuite:creditmemo:184921", "nullable": true }, "billingAddress": { "description": "Billing address for this credit note", "allOf": [ { "$ref": "#/components/schemas/AddressDto" } ] }, "file": { "type": "string", "description": "Credit note document file (PDF or image). Supports binary upload (default) or base64 encoding. For base64, set Content-Transfer-Encoding: base64 in the file part header. Maximum size: 10MB (decoded binary size).", "format": "binary" } }, "required": [ "accountId", "number", "issuedDate", "totalAmount", "taxAmount", "billingAddress", "file" ] }, "CreditNoteResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the credit note (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "number": { "type": "string", "description": "Credit note number", "example": "CN-2024-001" }, "issuedDate": { "description": "Date when the credit note was issued", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "totalAmount": { "type": "number", "description": "Total amount of the credit note including taxes", "example": 500 }, "taxAmount": { "type": "number", "description": "Tax amount included in total", "example": 83.33 }, "creditAllocations": { "type": "array", "items": { "description": "List of credit allocations from this credit note to invoices", "type": "array", "items": { "$ref": "#/components/schemas/CreditAllocationResponseDto" } } }, "billingAddress": { "description": "Billing address for this credit note", "allOf": [ { "$ref": "#/components/schemas/AddressResponseDto" } ] }, "creditAmount": { "type": "number", "description": "Total amount of credits allocated from this credit note", "example": 200 }, "refundedAmount": { "type": "number", "description": "Total refunded amount (cash refunds)", "example": 50 }, "remainingAmount": { "type": "number", "description": "Remaining amount available for allocation", "example": 300 }, "status": { "type": "string", "description": "Current status of the credit note", "enum": [ "Issued", "PartiallySettled", "Settled" ], "example": "PartiallySettled" }, "filestoreId": { "type": "string", "description": "Unique identifier of the stored credit note file (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174003", "format": "uuid" }, "channel": { "type": "string", "description": "Channel through which the credit note was issued", "enum": [ "Pennylane", "Qonto", "Sellsy", "Stripe", "ZohoBooks", "Api", "PublicApi", "AdminApi", "Mcp", "Manual" ], "example": "Manual" }, "connectionId": { "type": "string", "description": "The connection that issued this credit note, or null when no connector did. Frozen at issuance, and never set by a public API call.", "example": "123e4567-e89b-12d3-a456-426614174004", "format": "uuid", "nullable": true }, "sourceId": { "type": "string", "description": "Your own identifier for this credit note in the system it comes from, as sent at creation. Unique within the organization, frozen at issuance.", "example": "netsuite:creditmemo:184921", "nullable": true } }, "required": [ "id", "organizationId", "accountId", "number", "issuedDate", "totalAmount", "taxAmount", "creditAllocations", "billingAddress", "creditAmount", "refundedAmount", "remainingAmount", "status", "filestoreId", "channel", "connectionId", "sourceId" ] }, "CreditNoteDetailResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the credit note (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "number": { "type": "string", "description": "Credit note number", "example": "CN-2024-001" }, "issuedDate": { "description": "Date when the credit note was issued", "allOf": [ { "$ref": "#/components/schemas/date_value_response_dto_DateValueResponseDto" } ] }, "totalAmount": { "type": "number", "description": "Total amount of the credit note including taxes", "example": 500 }, "taxAmount": { "type": "number", "description": "Tax amount included in total", "example": 83.33 }, "creditAllocations": { "type": "array", "items": { "description": "List of credit allocations from this credit note to invoices", "type": "array", "items": { "$ref": "#/components/schemas/CreditAllocationResponseDto" } } }, "billingAddress": { "description": "Billing address for this credit note", "allOf": [ { "$ref": "#/components/schemas/AddressResponseDto" } ] }, "creditAmount": { "type": "number", "description": "Total amount of credits allocated from this credit note", "example": 200 }, "refundedAmount": { "type": "number", "description": "Total refunded amount (cash refunds)", "example": 50 }, "remainingAmount": { "type": "number", "description": "Remaining amount available for allocation", "example": 300 }, "status": { "type": "string", "description": "Current status of the credit note", "enum": [ "Issued", "PartiallySettled", "Settled" ], "example": "PartiallySettled" }, "filestoreId": { "type": "string", "description": "Unique identifier of the stored credit note file (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174003", "format": "uuid" }, "channel": { "type": "string", "description": "Channel through which the credit note was issued", "enum": [ "Pennylane", "Qonto", "Sellsy", "Stripe", "ZohoBooks", "Api", "PublicApi", "AdminApi", "Mcp", "Manual" ], "example": "Manual" }, "connectionId": { "type": "string", "description": "The connection that issued this credit note, or null when no connector did. Frozen at issuance, and never set by a public API call.", "example": "123e4567-e89b-12d3-a456-426614174004", "format": "uuid", "nullable": true }, "sourceId": { "type": "string", "description": "Your own identifier for this credit note in the system it comes from, as sent at creation. Unique within the organization, frozen at issuance.", "example": "netsuite:creditmemo:184921", "nullable": true }, "readOnlyReason": { "description": "Why this credit note refuses writes, or null when it accepts them. Do not derive this from `channel`: a connector-issued credit note becomes writable again once its account is unlinked. A delete attempted while this is set fails with app-invoicing.document.managed-action-forbidden, whose `details` repeats it.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/ReadOnlyReasonResponseDto" } ] } }, "required": [ "id", "organizationId", "accountId", "number", "issuedDate", "totalAmount", "taxAmount", "creditAllocations", "billingAddress", "creditAmount", "refundedAmount", "remainingAmount", "status", "filestoreId", "channel", "connectionId", "sourceId", "readOnlyReason" ] }, "SetCreditNoteRefundedAmountDto": { "type": "object", "properties": { "refundedAmount": { "type": "number", "description": "New refunded amount for the credit note", "example": 300, "minimum": 0 } }, "required": [ "refundedAmount" ] }, "ApplyCreditAllocationDto": { "type": "object", "properties": { "creditNoteId": { "type": "string", "description": "Credit note ID to allocate from (UUID v4)", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "invoiceId": { "type": "string", "description": "Invoice ID to allocate credit to (UUID v4)", "format": "uuid", "example": "987fcdeb-51a2-3b4c-d5e6-789012345678" }, "amount": { "type": "number", "description": "Amount of credit to allocate", "example": 100, "minimum": 0 } }, "required": [ "creditNoteId", "invoiceId", "amount" ] }, "PauseAuthorResponseDto": { "type": "object", "properties": { "userId": { "type": "string", "description": "Unique identifier of the user who paused (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174003", "format": "uuid" }, "userFullName": { "type": "string", "description": "Display name of that user, null when unknown", "example": "Marie Dupont", "nullable": true }, "channel": { "type": "string", "description": "Entry point the pause came through. Null for a pause posed before entry points were told apart", "example": "PublicApi", "enum": [ "Webapp", "PublicApi", "Mcp" ], "nullable": true } }, "required": [ "userId", "userFullName", "channel" ] }, "AccountPauseResponseDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Reason keeping payment follow-up paused", "example": "manual" }, "pausedAt": { "type": "string", "description": "When this pause was posed", "example": "2026-07-12T09:31:04.000Z", "format": "date-time" }, "pausedBy": { "description": "The user who asked for the pause. Null when the agent posed it rather than a user", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/PauseAuthorResponseDto" } ] } }, "required": [ "reason", "pausedAt", "pausedBy" ] }, "DunningHoldReason": { "type": "string", "enum": [ "payment-declared", "client-requested-date", "communicated-deadline", "negotiation-in-progress" ], "description": "Reason for waiting until that date" }, "DunningHoldResponseDto": { "type": "object", "properties": { "until": { "type": "string", "description": "When payment follow-up resumes automatically", "example": "2026-08-20T09:00:00.000Z", "format": "date-time" }, "reason": { "description": "Reason for waiting until that date", "allOf": [ { "$ref": "#/components/schemas/DunningHoldReason" } ] } }, "required": [ "until", "reason" ] }, "AccountDunningStatusResponseDto": { "type": "object", "properties": { "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization owning the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "isDunningPaused": { "type": "boolean", "description": "Whether dunning is currently paused for this account", "example": false }, "isManuallyPaused": { "type": "boolean", "description": "Whether dunning is manually paused for this account", "example": false }, "pauseReasons": { "description": "Active reasons currently pausing payment follow-up", "example": [ "manual" ], "type": "array", "items": { "type": "string" } }, "userResumablePauseReasons": { "description": "Active pause reasons a generic resume requested by a user would lift", "example": [ "manual" ], "type": "array", "items": { "type": "string" } }, "pauses": { "description": "Same set as pauseReasons, with the date and the author of each pause", "type": "array", "items": { "$ref": "#/components/schemas/AccountPauseResponseDto" } }, "dunningHold": { "description": "Active dated suspension. Null when no dated wait currently stops payment follow-up", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/DunningHoldResponseDto" } ] }, "hasCustomerOutstandingBalance": { "type": "boolean", "description": "Whether the account still has an outstanding balance to chase. False leaves payment follow-up idle whatever the pauses say", "example": true }, "firstOutreachApprovedAt": { "type": "string", "description": "When the organization requires it, the moment a person approved the very first outreach on this account. Null when no approval was given yet, or when the organization does not require one", "example": "2026-07-12T09:31:04.000Z", "format": "date-time", "nullable": true }, "isBelowMinimumDunningAmount": { "type": "boolean", "description": "The amount the next reminder would concern is below the organization's minimum, so nothing is sent. Not a pause: there is no reason to lift, and a new due installment or invoice reaching the floor resumes the cadence on its own", "example": false }, "minimumDunningAmount": { "type": "number", "description": "The floor the organization configured, expressed in minimumDunningAmountCurrency. Null when no floor is configured", "example": 50, "nullable": true }, "minimumDunningAmountCurrency": { "type": "string", "description": "Currency of the configured floor. Null on a legacy setting written before currencies existed, which means \"N units of each account's own currency\", never \"no floor\"", "example": "EUR", "nullable": true }, "accountCurrencyCode": { "type": "string", "description": "Currency the account is billed in. Null when the account could not be read", "example": "EUR", "nullable": true }, "minimumDunningAmountInAccountCurrency": { "type": "number", "description": "The same floor converted into the account's currency, which is what the send gate compares. Equal to minimumDunningAmount when no conversion applies. Null when there is no floor, or when the rate could not be read", "example": 50, "nullable": true }, "isMinimumDunningAmountUnavailable": { "type": "boolean", "description": "The conversion rate was unreachable, so nothing here can say whether the account is below the floor: isBelowMinimumDunningAmount is false because it is unknown, not because it is false. Report the unknown rather than a status made up from the flag", "example": false }, "isConnectorSyncStale": { "type": "boolean", "description": "The last extraction of the connector managing this account is too old, so payment follow-up is withheld on stale data. False for an account no connector drives, and false when the freshness could not be read: that read fails open, exactly like the send gate. Only true carries information", "example": false }, "firstReminderEligibleAt": { "type": "string", "description": "Date from which the very first automatic reminder becomes possible, when that rule is what holds the account back today. Null in every other case: no rule configured, no usable due date, a reminder already sent, or the date already reached", "example": "2026-08-30T00:00:00.000Z", "format": "date-time", "nullable": true }, "silenceReason": { "type": "string", "description": "The one ranked reason nothing is planned on this account, or null when nothing holds it back and a message is being written. Read this rather than ranking the flags above yourself: the order is decided once, alongside the send gate, so the webapp, this API and the MCP server all name the same cause. `suspended` outranks `blocking-task`, then `below-minimum-amount`, then `connector-sync-stale`, then `first-reminder-delay`", "enum": [ "suspended", "blocking-task", "below-minimum-amount", "connector-sync-stale", "first-reminder-delay" ], "example": "connector-sync-stale", "nullable": true } }, "required": [ "accountId", "organizationId", "isDunningPaused", "isManuallyPaused", "pauseReasons", "userResumablePauseReasons", "pauses", "dunningHold", "hasCustomerOutstandingBalance", "firstOutreachApprovedAt", "isBelowMinimumDunningAmount", "minimumDunningAmount", "minimumDunningAmountCurrency", "accountCurrencyCode", "minimumDunningAmountInAccountCurrency", "isMinimumDunningAmountUnavailable", "isConnectorSyncStale", "firstReminderEligibleAt", "silenceReason" ] }, "DunningSuspensionReason": { "type": "string", "enum": [ "stop-requested", "legal-procedure", "payment-plan", "dispute", "manual", "payment-declared", "client-requested-date", "communicated-deadline", "negotiation-in-progress" ], "description": "Why payment follow-up is suspended. Facts, without until: dispute, invoice contested by the debtor; payment-plan, an installment plan is in place; legal-procedure, legal proceedings are under way; stop-requested, the debtor asked to stop being contacted; manual, any other reason and the default when omitted. Dated waits, with until and automatic resume: payment-declared, the debtor says payment was sent and arrival is pending; client-requested-date, the debtor asked to be recontacted at a date; communicated-deadline, the debtor committed to a payment date; negotiation-in-progress, terms are being negotiated and should be checked later." }, "PauseAccountDunningDto": { "type": "object", "properties": { "reason": { "description": "Why payment follow-up is suspended. Facts, without until: dispute, invoice contested by the debtor; payment-plan, an installment plan is in place; legal-procedure, legal proceedings are under way; stop-requested, the debtor asked to stop being contacted; manual, any other reason and the default when omitted. Dated waits, with until and automatic resume: payment-declared, the debtor says payment was sent and arrival is pending; client-requested-date, the debtor asked to be recontacted at a date; communicated-deadline, the debtor committed to a payment date; negotiation-in-progress, terms are being negotiated and should be checked later.", "allOf": [ { "$ref": "#/components/schemas/DunningSuspensionReason" } ] }, "until": { "type": "string", "description": "Required with a dated wait reason and forbidden with a fact reason. ISO 8601 date-time in the future. Payment follow-up resumes automatically after this date.", "format": "date-time" } } }, "DateValueResponseDto": { "type": "object", "properties": { "year": { "type": "number", "description": "Year component of the date", "example": 2024 }, "month": { "type": "number", "description": "Month component of the date (1-12)", "example": 12, "minimum": 1, "maximum": 12 }, "day": { "type": "number", "description": "Day component of the date (1-31)", "example": 15, "minimum": 1, "maximum": 31 } }, "required": [ "year", "month", "day" ] }, "DunningInvoiceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the invoice (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "remainingBalance": { "type": "number", "description": "Remaining balance on the invoice", "example": 500 }, "dueDate": { "description": "Payment due date", "allOf": [ { "$ref": "#/components/schemas/DateValueResponseDto" } ] } }, "required": [ "id", "remainingBalance", "dueDate" ] }, "DunningCreditNoteResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the credit note (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "remainingAmount": { "type": "number", "description": "Remaining amount on the credit note", "example": 100 } }, "required": [ "id", "remainingAmount" ] }, "NextCommunicationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the next communication (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "type": { "type": "string", "description": "Type of the next communication", "enum": [ "OutgoingEmail" ], "example": "OutgoingEmail" } }, "required": [ "id", "type" ] }, "CustomerOutstandingBalanceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the customer outstanding balance (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "invoices": { "type": "array", "items": { "description": "List of invoices associated with this balance", "type": "array", "items": { "$ref": "#/components/schemas/DunningInvoiceResponseDto" } } }, "remainingBalance": { "type": "number", "description": "Total remaining balance across all invoices", "example": 1500 }, "creditNotes": { "type": "array", "items": { "description": "List of credit notes associated with this balance", "type": "array", "items": { "$ref": "#/components/schemas/DunningCreditNoteResponseDto" } } }, "nextCommunication": { "description": "Next scheduled communication", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/NextCommunicationResponseDto" } ] }, "isDunningPaused": { "type": "boolean", "description": "Whether dunning is currently paused for this account", "example": false }, "isManuallyPaused": { "type": "boolean", "description": "Whether dunning is manually paused for this account", "example": false }, "pauseReasons": { "description": "Active reasons currently pausing payment follow-up", "example": [ "manual", "tag:123e4567-e89b-12d3-a456-426614174003" ], "type": "array", "items": { "type": "string" } }, "dunningHold": { "description": "Active dated suspension. Null when no dated wait currently stops payment follow-up", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/DunningHoldResponseDto" } ] }, "score": { "type": "number", "description": "Credit score of the customer", "example": 85 } }, "required": [ "id", "organizationId", "accountId", "invoices", "remainingBalance", "creditNotes", "nextCommunication", "isDunningPaused", "isManuallyPaused", "pauseReasons", "dunningHold", "score" ] }, "responses_paginated_response_dto_PageInfoDto": { "type": "object", "properties": { "endCursor": { "type": "string", "description": "Cursor to use for fetching the next page", "example": "eyJpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCJ9" } } }, "PaginatedCustomerOutstandingBalancesResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "description": "List of customer outstanding balances", "type": "array", "items": { "$ref": "#/components/schemas/CustomerOutstandingBalanceResponseDto" } } }, "pageInfo": { "description": "Pagination info", "allOf": [ { "$ref": "#/components/schemas/responses_paginated_response_dto_PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "CommunicationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the communication" }, "accountId": { "type": "object", "description": "Account the communication belongs to", "nullable": true }, "emailId": { "type": "object", "description": "Underlying email, null on SMS and postal mail", "nullable": true }, "type": { "type": "string", "description": "Communication type", "enum": [ "IncomingEmail", "OutgoingEmail", "OutgoingSms", "OutgoingTrackedLetter", "OutgoingRegisteredLetter" ] }, "direction": { "type": "string", "description": "Whether the communication was received or sent", "enum": [ "Incoming", "Outgoing" ] }, "status": { "type": "string", "description": "Communication status", "enum": [ "Received", "Scheduled", "Sent", "Unclassified", "Internal", "PendingReview", "Rejected" ] }, "accountName": { "type": "object", "description": "Account name", "nullable": true }, "accountDeletedAt": { "type": "string", "description": "When the account was deleted, null while it still exists. The communication outlives its account: accountId and accountName stay filled, but GET /accounts/{accountId} answers 404 once this is set", "format": "date-time", "nullable": true }, "contactName": { "type": "object", "description": "Contact name", "nullable": true }, "subject": { "type": "string", "description": "Subject" }, "date": { "type": "string", "description": "When the communication was sent or received", "format": "date-time" }, "deliveryStatus": { "type": "object", "description": "Delivery status: provider status on emails, SMS and postal mail", "nullable": true } }, "required": [ "id", "accountId", "emailId", "type", "direction", "status", "accountName", "accountDeletedAt", "contactName", "subject", "date", "deliveryStatus" ] }, "PaginatedCommunicationsResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "description": "List of communications", "type": "array", "items": { "$ref": "#/components/schemas/CommunicationResponseDto" } } }, "pageInfo": { "description": "Pagination info", "allOf": [ { "$ref": "#/components/schemas/responses_paginated_response_dto_PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "EmailCommunicationStatusHistoryResponseDto": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the email communication", "enum": [ "Send", "Delivered", "HardBounced", "SoftBounced", "Opened", "Complained" ], "example": "Delivered" }, "timestamp": { "type": "string", "description": "Timestamp when this status was recorded (ISO 8601)", "example": "2024-12-15T10:30:00.000Z" } }, "required": [ "status", "timestamp" ] }, "OutgoingEmailCommunicationSummaryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the outgoing email communication (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "emailId": { "type": "string", "description": "Unique identifier of the associated email (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174003", "format": "uuid" }, "accountDeleted": { "type": "boolean", "description": "Whether the account this communication belonged to has been deleted. The communication outlives its account, so accountId stays filled but reading the account answers 404 once this is true", "example": false }, "recipientsStatusHistory": { "type": "object", "description": "Status history per recipient email address", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/EmailCommunicationStatusHistoryResponseDto" } }, "example": { "recipient@example.com": [ { "status": "Send", "timestamp": "2024-12-15T10:30:00.000Z" }, { "status": "Delivered", "timestamp": "2024-12-15T10:31:00.000Z" } ] } } }, "required": [ "id", "organizationId", "accountId", "emailId", "accountDeleted", "recipientsStatusHistory" ] }, "PaginatedOutgoingEmailCommunicationsResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "description": "List of outgoing email communications", "type": "array", "items": { "$ref": "#/components/schemas/OutgoingEmailCommunicationSummaryResponseDto" } } }, "pageInfo": { "description": "Pagination info", "allOf": [ { "$ref": "#/components/schemas/responses_paginated_response_dto_PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "EmailAddressResponseDto": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address", "example": "john.doe@example.com" }, "name": { "type": "string", "description": "Display name associated with the email address", "example": "John Doe", "nullable": true } }, "required": [ "address", "name" ] }, "EmailBodyResponseDto": { "type": "object", "properties": { "text": { "type": "string", "description": "Plain text content of the email", "example": "Hello, this is the email content.", "nullable": true }, "html": { "type": "string", "description": "HTML content of the email", "example": "

Hello, this is the email content.

", "nullable": true } }, "required": [ "text", "html" ] }, "OutgoingEmailResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the email (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid", "nullable": true }, "from": { "description": "Sender email address", "allOf": [ { "$ref": "#/components/schemas/EmailAddressResponseDto" } ] }, "to": { "type": "array", "items": { "description": "List of recipient email addresses", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressResponseDto" } } }, "cc": { "type": "array", "items": { "description": "List of CC recipient email addresses", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressResponseDto" } } }, "bcc": { "type": "array", "items": { "description": "List of BCC recipient email addresses", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressResponseDto" } } }, "subject": { "type": "string", "description": "Email subject", "example": "Invoice reminder - INV-2024-001" }, "body": { "description": "Email body content", "allOf": [ { "$ref": "#/components/schemas/EmailBodyResponseDto" } ] }, "inReplyTo": { "type": "string", "description": "Message ID of the email being replied to", "example": "", "nullable": true }, "references": { "description": "List of message IDs in the email thread", "items": { "type": "array", "items": { "type": "string" } }, "type": "array" }, "attachments": { "description": "List of attachment file IDs", "items": { "type": "array", "items": { "type": "string" } }, "type": "array" }, "messageIds": { "type": "object", "description": "Map of message IDs to recipient email addresses", "additionalProperties": { "type": "string" }, "example": { "": "recipient@example.com" }, "nullable": true }, "sentAt": { "type": "string", "description": "Timestamp when the email was sent (ISO 8601)", "example": "2024-12-15T10:30:00.000Z", "nullable": true }, "scheduledAt": { "type": "string", "description": "Timestamp when the email is scheduled to be sent (ISO 8601)", "example": "2024-12-16T09:00:00.000Z" } }, "required": [ "id", "organizationId", "from", "to", "cc", "bcc", "subject", "body", "inReplyTo", "references", "attachments", "messageIds", "sentAt", "scheduledAt" ] }, "OutgoingEmailCommunicationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the outgoing email communication (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "emailId": { "type": "string", "description": "Unique identifier of the associated email (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174003", "format": "uuid" }, "accountDeleted": { "type": "boolean", "description": "Whether the account this communication belonged to has been deleted. The communication outlives its account, so accountId stays filled but reading the account answers 404 once this is true", "example": false }, "recipientsStatusHistory": { "type": "object", "description": "Status history per recipient email address", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/EmailCommunicationStatusHistoryResponseDto" } }, "example": { "recipient@example.com": [ { "status": "Send", "timestamp": "2024-12-15T10:30:00.000Z" }, { "status": "Delivered", "timestamp": "2024-12-15T10:31:00.000Z" } ] } }, "email": { "description": "The associated outgoing email", "allOf": [ { "$ref": "#/components/schemas/OutgoingEmailResponseDto" } ] } }, "required": [ "id", "organizationId", "accountId", "emailId", "accountDeleted", "recipientsStatusHistory", "email" ] }, "EmailAddressDto": { "type": "object", "properties": { "address": { "type": "string", "description": "Email address", "example": "john.doe@example.com" }, "name": { "type": "string", "description": "Display name associated with the email address", "example": "John Doe", "nullable": true } }, "required": [ "address" ] }, "UpdateOutgoingEmailCommunicationDto": { "type": "object", "properties": { "to": { "type": "array", "items": { "description": "List of recipient email addresses", "required": false, "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressDto" } } }, "cc": { "type": "array", "items": { "description": "List of CC recipient email addresses", "required": false, "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressDto" } } }, "bcc": { "type": "array", "items": { "description": "List of BCC recipient email addresses", "required": false, "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressDto" } } }, "subject": { "type": "string", "description": "Email subject", "example": "Invoice reminder - INV-2024-001", "nullable": true }, "inReplyTo": { "type": "string", "description": "Message ID of the email being replied to", "example": "", "nullable": true }, "references": { "description": "List of message IDs in the email thread", "nullable": true, "items": { "type": "array", "items": { "type": "string" } }, "type": "array" }, "message": { "type": "string", "description": "Email body content in markdown. Do not include a signature; the platform adds it automatically.", "example": "Bonjour,\n\nJe vous contacte au sujet de la facture **INV-2024-001**.\n\nMerci pour votre retour.", "nullable": true }, "language": { "type": "string", "description": "Language code for the email (e.g., en, fr)", "example": "en", "nullable": true }, "scheduledAt": { "type": "string", "description": "Timestamp when the email is scheduled to be sent (ISO 8601)", "example": "2024-12-16T09:00:00.000Z", "nullable": true }, "attachments": { "description": "List of attachment file IDs. Restricted to files the server already vouched for on this communication: those already attached to the email, those of its financial manifest, and its bank details document. Any other identifier is rejected, and a financial document the reminder declared required cannot be removed. Omit the field to keep the current attachments.", "nullable": true, "items": { "type": "array", "items": { "type": "string" } }, "type": "array" } }, "required": [ "to", "cc", "bcc" ] }, "AttachmentFileDto": { "type": "object", "properties": { "content": { "type": "string", "description": "Base64-encoded file content" }, "filename": { "type": "string", "description": "Filename with extension (e.g., proof.pdf)", "example": "proof.pdf" }, "mimeType": { "type": "string", "description": "File MIME type", "enum": [ "application/pdf", "image/jpeg", "image/png", "image/webp" ] } }, "required": [ "content", "filename", "mimeType" ] }, "SendOutgoingEmailCommunicationDto": { "type": "object", "properties": { "to": { "type": "array", "items": { "description": "List of recipient email addresses", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressDto" } } }, "cc": { "type": "array", "items": { "description": "List of CC recipient email addresses", "required": false, "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressDto" } } }, "bcc": { "type": "array", "items": { "description": "List of BCC recipient email addresses", "required": false, "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressDto" } } }, "subject": { "type": "string", "description": "Email subject", "example": "Invoice reminder - INV-2024-001" }, "message": { "type": "string", "description": "Email body content in markdown. Do not include a signature; the platform adds it automatically.", "example": "Bonjour,\n\nJe vous contacte au sujet de la facture **INV-2024-001**.\n\nMerci pour votre retour." }, "language": { "type": "string", "description": "Language code for the email (e.g., en, fr)", "example": "en", "nullable": true }, "attachmentIds": { "description": "Technical IDs of existing filestore attachments to include (e.g. an invoice or credit note filestoreId)", "nullable": true, "items": { "type": "array", "items": { "type": "string" } }, "type": "array" }, "files": { "type": "array", "items": { "description": "New files to attach, base64-encoded. Each file must not exceed 10MB.", "required": false, "nullable": true, "type": "array", "items": { "$ref": "#/components/schemas/AttachmentFileDto" } } } }, "required": [ "to", "cc", "bcc", "subject", "message", "files" ] }, "OutgoingLetterAddressDto": { "type": "object", "properties": { "fullName": { "type": "string", "example": "Client SA" }, "street": { "type": "string", "example": "1 rue de la Paix" }, "postalCode": { "type": "string", "example": "75001" }, "city": { "type": "string", "example": "Paris" }, "country": { "type": "string", "example": "FR", "enum": [ "FR" ] } }, "required": [ "fullName", "street", "postalCode", "city", "country" ] }, "PreviewOutgoingLetterDto": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "TrackedLetter", "RegisteredLetter" ] }, "invoiceIds": { "description": "Invoice IDs to claim and append as evidence", "type": "array", "items": { "type": "string" } }, "creditNoteIds": { "description": "Credit note IDs to deduct and append. Omit to deduct every available credit note; send an empty list to deduct none.", "type": "array", "items": { "type": "string" } }, "paymentDeadline": { "type": "string", "description": "Future payment deadline in YYYY-MM-DD format", "example": "2026-08-20" }, "body": { "type": "string", "description": "Optional edited letter body. The standard template is used when omitted." }, "recipientAddress": { "description": "Address for this letter. The account billing address is used when omitted.", "allOf": [ { "$ref": "#/components/schemas/OutgoingLetterAddressDto" } ] }, "includePdf": { "type": "boolean", "description": "Also assemble and return the complete PDF as base64", "default": false } }, "required": [ "channel", "invoiceIds", "paymentDeadline" ] }, "OutgoingLetterPreviewResponseDto": { "type": "object", "properties": { "pdfBase64": { "type": "string", "nullable": true }, "html": { "type": "string" }, "body": { "type": "string" }, "pageCount": { "type": "number" }, "credits": { "type": "number" } }, "required": [ "pdfBase64", "html", "body", "pageCount", "credits" ] }, "SendOutgoingLetterDto": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "TrackedLetter", "RegisteredLetter" ] }, "invoiceIds": { "description": "Invoice IDs to claim and append as evidence", "type": "array", "items": { "type": "string" } }, "creditNoteIds": { "description": "Credit note IDs to deduct and append. Omit to deduct every available credit note; send an empty list to deduct none.", "type": "array", "items": { "type": "string" } }, "paymentDeadline": { "type": "string", "description": "Future payment deadline in YYYY-MM-DD format", "example": "2026-08-20" }, "body": { "type": "string", "description": "Optional edited letter body. The standard template is used when omitted." }, "recipientAddress": { "description": "Address for this letter. The account billing address is used when omitted.", "allOf": [ { "$ref": "#/components/schemas/OutgoingLetterAddressDto" } ] }, "taskId": { "type": "string", "description": "Task answered by this send", "format": "uuid" }, "idempotencyKey": { "type": "string", "maxLength": 256 }, "maxCredits": { "type": "number", "minimum": 0 } }, "required": [ "channel", "invoiceIds", "paymentDeadline" ] }, "OutgoingLetterAddressResponseDto": { "type": "object", "properties": { "fullName": { "type": "string" }, "street": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "fullName", "street", "postalCode", "city", "country" ] }, "OutgoingLetterResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "channel": { "type": "string", "enum": [ "Sms", "TrackedLetter", "RegisteredLetter" ] }, "body": { "type": "string" }, "invoiceIds": { "type": "array", "items": { "type": "string" } }, "authorizedPaymentDeadline": { "type": "string" }, "creditsCharged": { "type": "number" }, "recipientAddress": { "$ref": "#/components/schemas/OutgoingLetterAddressResponseDto" }, "trackingRef": { "type": "string", "nullable": true }, "deliveryStatus": { "type": "string", "nullable": true, "enum": [ "Sent", "Delivered", "Failed", "Returned" ] } }, "required": [ "id", "organizationId", "accountId", "channel", "body", "invoiceIds", "authorizedPaymentDeadline", "creditsCharged", "recipientAddress", "trackingRef", "deliveryStatus" ] }, "OutgoingMessageAddressDto": { "type": "object", "properties": { "fullName": { "type": "string", "example": "Client SA" }, "street": { "type": "string", "example": "1 rue de la Paix" }, "postalCode": { "type": "string", "example": "75001" }, "city": { "type": "string", "example": "Paris" }, "country": { "type": "string", "example": "FR", "enum": [ "FR" ] } }, "required": [ "fullName", "street", "postalCode", "city", "country" ] }, "PreviewOutgoingMessageCommunicationDto": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "Sms", "TrackedLetter", "RegisteredLetter" ] }, "contactId": { "type": "string", "format": "uuid" }, "invoiceIds": { "description": "Overdue invoice IDs to claim", "type": "array", "items": { "type": "string" } }, "creditNoteIds": { "type": "array", "items": { "type": "string" } }, "paymentDeadline": { "type": "string", "example": "2026-08-25" }, "body": { "type": "string" }, "recipientPhone": { "type": "string", "example": "+33612345678" }, "recipientAddress": { "$ref": "#/components/schemas/OutgoingMessageAddressDto" }, "includePdf": { "type": "boolean", "default": false } }, "required": [ "channel", "invoiceIds", "paymentDeadline" ] }, "OutgoingMessageCommunicationPreviewResponseDto": { "type": "object", "properties": { "pdfBase64": { "type": "string", "nullable": true }, "html": { "type": "string", "description": "Rendered letter HTML, empty for SMS" }, "body": { "type": "string" }, "pageCount": { "type": "number", "description": "Postal page count, zero for SMS" }, "credits": { "type": "number" } }, "required": [ "pdfBase64", "html", "body", "pageCount", "credits" ] }, "SendOutgoingMessageCommunicationDto": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "Sms", "TrackedLetter", "RegisteredLetter" ] }, "contactId": { "type": "string", "format": "uuid" }, "invoiceIds": { "description": "Overdue invoice IDs to claim", "type": "array", "items": { "type": "string" } }, "creditNoteIds": { "type": "array", "items": { "type": "string" } }, "paymentDeadline": { "type": "string", "example": "2026-08-25" }, "body": { "type": "string" }, "recipientPhone": { "type": "string", "example": "+33612345678" }, "recipientAddress": { "$ref": "#/components/schemas/OutgoingMessageAddressDto" }, "taskId": { "type": "string", "format": "uuid" }, "idempotencyKey": { "type": "string", "description": "Stable key that makes retries return the first recorded send", "maxLength": 256 }, "maxCredits": { "type": "number", "description": "Maximum credits this request may spend", "minimum": 0 } }, "required": [ "channel", "invoiceIds", "paymentDeadline" ] }, "OutgoingMessageRecipientAddressResponseDto": { "type": "object", "properties": { "fullName": { "type": "string" }, "street": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "fullName", "street", "postalCode", "city", "country" ] }, "OutgoingMessageDeliveryStatusHistoryResponseDto": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Sent", "Delivered", "Failed", "Returned" ] }, "detail": { "type": "string", "nullable": true }, "timestamp": { "format": "date-time", "type": "string" } }, "required": [ "status", "detail", "timestamp" ] }, "OutgoingMessageCommunicationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organizationId": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "accountDeleted": { "type": "boolean", "description": "Whether the account this message belonged to has been deleted. The message outlives its account, so accountId stays filled but reading the account answers 404 once this is true" }, "channel": { "type": "string", "enum": [ "Sms", "TrackedLetter", "RegisteredLetter" ] }, "contactId": { "type": "string", "format": "uuid", "nullable": true }, "body": { "type": "string" }, "invoiceIds": { "type": "array", "items": { "type": "string" } }, "authorizedPaymentDeadline": { "type": "string" }, "creditsCharged": { "type": "number" }, "recipientPhone": { "type": "string", "nullable": true }, "recipientAddress": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/OutgoingMessageRecipientAddressResponseDto" } ] }, "trackingRef": { "type": "string", "nullable": true }, "deliveryStatus": { "type": "string", "nullable": true, "enum": [ "Sent", "Delivered", "Failed", "Returned" ] }, "statusHistory": { "type": "array", "items": { "$ref": "#/components/schemas/OutgoingMessageDeliveryStatusHistoryResponseDto" } } }, "required": [ "id", "organizationId", "accountId", "accountDeleted", "channel", "contactId", "body", "invoiceIds", "authorizedPaymentDeadline", "creditsCharged", "recipientPhone", "recipientAddress", "trackingRef", "deliveryStatus", "statusHistory" ] }, "IncomingEmailCommunicationSummaryResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the incoming email communication (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "emailId": { "type": "string", "description": "Unique identifier of the associated email (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174003", "format": "uuid" }, "accountDeleted": { "type": "boolean", "description": "Whether the account this communication belonged to has been deleted. The communication outlives its account, so accountId stays filled but reading the account answers 404 once this is true", "example": false } }, "required": [ "id", "organizationId", "accountId", "emailId", "accountDeleted" ] }, "PaginatedIncomingEmailCommunicationsResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "description": "List of incoming email communications", "type": "array", "items": { "$ref": "#/components/schemas/IncomingEmailCommunicationSummaryResponseDto" } } }, "pageInfo": { "description": "Pagination info", "allOf": [ { "$ref": "#/components/schemas/responses_paginated_response_dto_PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "IncomingEmailResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the email (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "from": { "description": "Sender email address", "allOf": [ { "$ref": "#/components/schemas/EmailAddressResponseDto" } ] }, "to": { "type": "array", "items": { "description": "List of recipient email addresses", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressResponseDto" } } }, "cc": { "type": "array", "items": { "description": "List of CC recipient email addresses", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressResponseDto" } } }, "subject": { "type": "string", "description": "Email subject", "example": "Re: Invoice reminder - INV-2024-001" }, "body": { "description": "Email body content", "allOf": [ { "$ref": "#/components/schemas/EmailBodyResponseDto" } ] }, "inReplyTo": { "type": "string", "description": "Message ID of the email being replied to", "example": "", "nullable": true }, "references": { "description": "List of message IDs in the email thread", "items": { "type": "array", "items": { "type": "string" } }, "type": "array" }, "attachments": { "description": "List of attachment file IDs", "items": { "type": "array", "items": { "type": "string" } }, "type": "array" }, "messageId": { "type": "string", "description": "Unique message ID of this email", "example": "" }, "receivedAt": { "type": "string", "description": "Timestamp when the email was received (ISO 8601)", "example": "2024-12-15T14:30:00.000Z" } }, "required": [ "id", "from", "to", "cc", "subject", "body", "inReplyTo", "references", "attachments", "messageId", "receivedAt" ] }, "IncomingEmailCommunicationResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the incoming email communication (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "organizationId": { "type": "string", "description": "Unique identifier of the organization (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "accountId": { "type": "string", "description": "Unique identifier of the account (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174002", "format": "uuid" }, "emailId": { "type": "string", "description": "Unique identifier of the associated email (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174003", "format": "uuid" }, "accountDeleted": { "type": "boolean", "description": "Whether the account this communication belonged to has been deleted. The communication outlives its account, so accountId stays filled but reading the account answers 404 once this is true", "example": false }, "email": { "description": "The associated incoming email", "allOf": [ { "$ref": "#/components/schemas/IncomingEmailResponseDto" } ] } }, "required": [ "id", "organizationId", "accountId", "emailId", "accountDeleted", "email" ] }, "ContactEmailDto": { "type": "object", "properties": { "address": { "type": "string", "description": "Contact email address", "example": "contact@company.com" }, "name": { "type": "string", "description": "Contact full name", "example": "Jane Doe" } }, "required": [ "address" ] }, "AccountTaskExtraDataApproveEligibilityDto": { "type": "object", "properties": { "contactEmail": { "description": "Contact email to approve", "allOf": [ { "$ref": "#/components/schemas/ContactEmailDto" } ] }, "refEmailMessageIds": { "description": "Referenced email message IDs", "example": [ "" ], "type": "array", "items": { "type": "string" } } }, "required": [ "contactEmail" ] }, "AccountTaskApproveEligibilityDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "accountId": { "type": "string", "description": "Account ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "title": { "type": "string", "description": "Task title", "example": "Approve new contact eligibility" }, "assignees": { "description": "Assignee user IDs", "example": [ "123e4567-e89b-12d3-a456-426614174003" ], "type": "array", "items": { "type": "string" } }, "thread": { "description": "Task thread of interactions", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/AgentInteractionDto" }, { "$ref": "#/components/schemas/UserInteractionDto" } ] } }, "isClosed": { "type": "boolean", "description": "Whether the task is closed" }, "isCanceled": { "type": "boolean", "description": "Whether the task is canceled" }, "createdAt": { "type": "string", "description": "Task creation timestamp", "example": "2024-05-01T10:15:30.000Z" }, "closedAt": { "type": "object", "description": "Task closed timestamp" }, "canceledAt": { "type": "object", "description": "Task canceled timestamp" }, "cancelReason": { "type": "object", "description": "Why the task was canceled, when a reason was given" }, "status": { "type": "string", "description": "Task status", "enum": [ "Open", "InProgress", "UserActionRequired", "Closed", "Canceled", "Pending" ] }, "isActive": { "type": "boolean", "description": "Whether the task is active" }, "completedAt": { "type": "object", "description": "Task completion timestamp" }, "isPending": { "type": "boolean", "description": "Whether the task is pending" }, "pendingAt": { "type": "object", "description": "Task pending timestamp" }, "type": { "type": "string", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ], "example": "ApproveEligibility" }, "extraData": { "description": "Extra data for approval tasks", "allOf": [ { "$ref": "#/components/schemas/AccountTaskExtraDataApproveEligibilityDto" } ] } }, "required": [ "id", "organizationId", "accountId", "title", "assignees", "isClosed", "isCanceled", "createdAt", "status", "isActive", "isPending", "type", "extraData" ] }, "ProposedContactOperationDto": { "type": "object", "properties": { "operation": { "type": "string", "description": "Operation to perform on the account contacts", "enum": [ "Add", "Remove", "Update" ], "example": "Remove" }, "email": { "type": "string", "description": "Email address of the contact targeted by the operation", "example": "contact@company.com" }, "fullName": { "type": "object", "description": "Full name of the contact to add (Add operations only)", "nullable": true, "example": "Jane Doe" }, "language": { "type": "object", "description": "ISO 639-1 language code of the contact to add (Add operations only)", "nullable": true, "example": "fr" }, "reason": { "type": "string", "description": "Why the agent proposes this operation", "example": "The sender states they no longer work at the company" }, "warnings": { "type": "array", "description": "Warnings the user should review before approving", "example": [ "WouldLeaveAccountWithoutContact" ], "items": { "type": "string", "enum": [ "WouldLeaveAccountWithoutContact", "TargetIsNotSender" ] } } }, "required": [ "operation", "email", "reason", "warnings" ] }, "AccountTaskExtraDataApproveContactChangeDto": { "type": "object", "properties": { "proposedOperations": { "description": "Contact operations proposed by the agent", "type": "array", "items": { "$ref": "#/components/schemas/ProposedContactOperationDto" } }, "refEmailMessageIds": { "description": "Referenced email message IDs", "example": [ "" ], "type": "array", "items": { "type": "string" } } }, "required": [ "proposedOperations" ] }, "AccountTaskApproveContactChangeDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "accountId": { "type": "string", "description": "Account ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "title": { "type": "string", "description": "Task title", "example": "Approve new contact eligibility" }, "assignees": { "description": "Assignee user IDs", "example": [ "123e4567-e89b-12d3-a456-426614174003" ], "type": "array", "items": { "type": "string" } }, "thread": { "description": "Task thread of interactions", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/AgentInteractionDto" }, { "$ref": "#/components/schemas/UserInteractionDto" } ] } }, "isClosed": { "type": "boolean", "description": "Whether the task is closed" }, "isCanceled": { "type": "boolean", "description": "Whether the task is canceled" }, "createdAt": { "type": "string", "description": "Task creation timestamp", "example": "2024-05-01T10:15:30.000Z" }, "closedAt": { "type": "object", "description": "Task closed timestamp" }, "canceledAt": { "type": "object", "description": "Task canceled timestamp" }, "cancelReason": { "type": "object", "description": "Why the task was canceled, when a reason was given" }, "status": { "type": "string", "description": "Task status", "enum": [ "Open", "InProgress", "UserActionRequired", "Closed", "Canceled", "Pending" ] }, "isActive": { "type": "boolean", "description": "Whether the task is active" }, "completedAt": { "type": "object", "description": "Task completion timestamp" }, "isPending": { "type": "boolean", "description": "Whether the task is pending" }, "pendingAt": { "type": "object", "description": "Task pending timestamp" }, "type": { "type": "string", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ], "example": "ApproveContactChange" }, "extraData": { "description": "Extra data for contact change approval tasks", "allOf": [ { "$ref": "#/components/schemas/AccountTaskExtraDataApproveContactChangeDto" } ] } }, "required": [ "id", "organizationId", "accountId", "title", "assignees", "isClosed", "isCanceled", "createdAt", "status", "isActive", "isPending", "type", "extraData" ] }, "AccountTaskExtraDataDto": { "type": "object", "properties": { "idempotencyKey": { "type": "string", "description": "Stable key scoping the uniqueness of this task within its account, when the agent set one.", "nullable": true, "example": "contact-grievance:123e4567-e89b-12d3-a456-426614174000" } }, "required": [ "idempotencyKey" ] }, "AccountTaskNeedContactsDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "accountId": { "type": "string", "description": "Account ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "title": { "type": "string", "description": "Task title", "example": "Approve new contact eligibility" }, "assignees": { "description": "Assignee user IDs", "example": [ "123e4567-e89b-12d3-a456-426614174003" ], "type": "array", "items": { "type": "string" } }, "thread": { "description": "Task thread of interactions", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/AgentInteractionDto" }, { "$ref": "#/components/schemas/UserInteractionDto" } ] } }, "isClosed": { "type": "boolean", "description": "Whether the task is closed" }, "isCanceled": { "type": "boolean", "description": "Whether the task is canceled" }, "createdAt": { "type": "string", "description": "Task creation timestamp", "example": "2024-05-01T10:15:30.000Z" }, "closedAt": { "type": "object", "description": "Task closed timestamp" }, "canceledAt": { "type": "object", "description": "Task canceled timestamp" }, "cancelReason": { "type": "object", "description": "Why the task was canceled, when a reason was given" }, "status": { "type": "string", "description": "Task status", "enum": [ "Open", "InProgress", "UserActionRequired", "Closed", "Canceled", "Pending" ] }, "isActive": { "type": "boolean", "description": "Whether the task is active" }, "completedAt": { "type": "object", "description": "Task completion timestamp" }, "isPending": { "type": "boolean", "description": "Whether the task is pending" }, "pendingAt": { "type": "object", "description": "Task pending timestamp" }, "type": { "type": "string", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ], "example": "NeedContacts" }, "extraData": { "description": "Extra data for need contacts tasks", "allOf": [ { "$ref": "#/components/schemas/AccountTaskExtraDataDto" } ] } }, "required": [ "id", "organizationId", "accountId", "title", "assignees", "isClosed", "isCanceled", "createdAt", "status", "isActive", "isPending", "type", "extraData" ] }, "AccountTaskAskNextActionDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "accountId": { "type": "string", "description": "Account ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "title": { "type": "string", "description": "Task title", "example": "Approve new contact eligibility" }, "assignees": { "description": "Assignee user IDs", "example": [ "123e4567-e89b-12d3-a456-426614174003" ], "type": "array", "items": { "type": "string" } }, "thread": { "description": "Task thread of interactions", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/AgentInteractionDto" }, { "$ref": "#/components/schemas/UserInteractionDto" } ] } }, "isClosed": { "type": "boolean", "description": "Whether the task is closed" }, "isCanceled": { "type": "boolean", "description": "Whether the task is canceled" }, "createdAt": { "type": "string", "description": "Task creation timestamp", "example": "2024-05-01T10:15:30.000Z" }, "closedAt": { "type": "object", "description": "Task closed timestamp" }, "canceledAt": { "type": "object", "description": "Task canceled timestamp" }, "cancelReason": { "type": "object", "description": "Why the task was canceled, when a reason was given" }, "status": { "type": "string", "description": "Task status", "enum": [ "Open", "InProgress", "UserActionRequired", "Closed", "Canceled", "Pending" ] }, "isActive": { "type": "boolean", "description": "Whether the task is active" }, "completedAt": { "type": "object", "description": "Task completion timestamp" }, "isPending": { "type": "boolean", "description": "Whether the task is pending" }, "pendingAt": { "type": "object", "description": "Task pending timestamp" }, "type": { "type": "string", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ], "example": "AskNextAction" }, "extraData": { "description": "Extra data for next action tasks", "allOf": [ { "$ref": "#/components/schemas/AccountTaskExtraDataDto" } ] } }, "required": [ "id", "organizationId", "accountId", "title", "assignees", "isClosed", "isCanceled", "createdAt", "status", "isActive", "isPending", "type", "extraData" ] }, "AccountTaskApproveFirstOutreachDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "accountId": { "type": "string", "description": "Account ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "title": { "type": "string", "description": "Task title", "example": "Approve new contact eligibility" }, "assignees": { "description": "Assignee user IDs", "example": [ "123e4567-e89b-12d3-a456-426614174003" ], "type": "array", "items": { "type": "string" } }, "thread": { "description": "Task thread of interactions", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/AgentInteractionDto" }, { "$ref": "#/components/schemas/UserInteractionDto" } ] } }, "isClosed": { "type": "boolean", "description": "Whether the task is closed" }, "isCanceled": { "type": "boolean", "description": "Whether the task is canceled" }, "createdAt": { "type": "string", "description": "Task creation timestamp", "example": "2024-05-01T10:15:30.000Z" }, "closedAt": { "type": "object", "description": "Task closed timestamp" }, "canceledAt": { "type": "object", "description": "Task canceled timestamp" }, "cancelReason": { "type": "object", "description": "Why the task was canceled, when a reason was given" }, "status": { "type": "string", "description": "Task status", "enum": [ "Open", "InProgress", "UserActionRequired", "Closed", "Canceled", "Pending" ] }, "isActive": { "type": "boolean", "description": "Whether the task is active" }, "completedAt": { "type": "object", "description": "Task completion timestamp" }, "isPending": { "type": "boolean", "description": "Whether the task is pending" }, "pendingAt": { "type": "object", "description": "Task pending timestamp" }, "type": { "type": "string", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ], "example": "ApproveFirstOutreach" }, "extraData": { "description": "Extra data for first outreach approval tasks", "allOf": [ { "$ref": "#/components/schemas/AccountTaskExtraDataDto" } ] } }, "required": [ "id", "organizationId", "accountId", "title", "assignees", "isClosed", "isCanceled", "createdAt", "status", "isActive", "isPending", "type", "extraData" ] }, "PaymentInstallmentDateDto": { "type": "object", "properties": { "year": { "type": "number", "description": "Year", "example": 2026 }, "month": { "type": "number", "description": "Month (1-12)", "example": 6 }, "day": { "type": "number", "description": "Day of month", "example": 15 } }, "required": [ "year", "month", "day" ] }, "account_task_extra_data_dto_PaymentInstallmentDto": { "type": "object", "properties": { "dueDate": { "description": "Installment due date", "allOf": [ { "$ref": "#/components/schemas/PaymentInstallmentDateDto" } ] }, "amount": { "type": "number", "description": "Installment amount", "example": 100 } }, "required": [ "dueDate", "amount" ] }, "AccountTaskExtraDataApprovePaymentArrangementDto": { "type": "object", "properties": { "sourceEmailId": { "type": "object", "description": "ID of the incoming email carrying the proposal", "nullable": true, "example": "123e4567-e89b-12d3-a456-426614174020" }, "invoiceIds": { "description": "Invoices the arrangement covers, frozen when the task was opened. The decision may only narrow this list.", "type": "array", "items": { "type": "string" } }, "proposedInstallments": { "description": "Installments the debtor stated explicitly. Empty or partial when the email named no figure: nothing here is inferred.", "type": "array", "items": { "$ref": "#/components/schemas/account_task_extra_data_dto_PaymentInstallmentDto" } }, "paymentPlanPauseApplied": { "type": "boolean", "description": "Whether the payment-plan pause was posed for this request, and may therefore be lifted by its decision", "example": false }, "refEmailMessageIds": { "description": "Reference email message IDs", "type": "array", "items": { "type": "string" } } }, "required": [ "sourceEmailId", "invoiceIds", "proposedInstallments", "paymentPlanPauseApplied", "refEmailMessageIds" ] }, "AccountTaskApprovePaymentArrangementDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "accountId": { "type": "string", "description": "Account ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "title": { "type": "string", "description": "Task title", "example": "Approve new contact eligibility" }, "assignees": { "description": "Assignee user IDs", "example": [ "123e4567-e89b-12d3-a456-426614174003" ], "type": "array", "items": { "type": "string" } }, "thread": { "description": "Task thread of interactions", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/AgentInteractionDto" }, { "$ref": "#/components/schemas/UserInteractionDto" } ] } }, "isClosed": { "type": "boolean", "description": "Whether the task is closed" }, "isCanceled": { "type": "boolean", "description": "Whether the task is canceled" }, "createdAt": { "type": "string", "description": "Task creation timestamp", "example": "2024-05-01T10:15:30.000Z" }, "closedAt": { "type": "object", "description": "Task closed timestamp" }, "canceledAt": { "type": "object", "description": "Task canceled timestamp" }, "cancelReason": { "type": "object", "description": "Why the task was canceled, when a reason was given" }, "status": { "type": "string", "description": "Task status", "enum": [ "Open", "InProgress", "UserActionRequired", "Closed", "Canceled", "Pending" ] }, "isActive": { "type": "boolean", "description": "Whether the task is active" }, "completedAt": { "type": "object", "description": "Task completion timestamp" }, "isPending": { "type": "boolean", "description": "Whether the task is pending" }, "pendingAt": { "type": "object", "description": "Task pending timestamp" }, "type": { "type": "string", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ], "example": "ApprovePaymentArrangement" }, "extraData": { "description": "Extra data for payment arrangement review tasks", "allOf": [ { "$ref": "#/components/schemas/AccountTaskExtraDataApprovePaymentArrangementDto" } ] } }, "required": [ "id", "organizationId", "accountId", "title", "assignees", "isClosed", "isCanceled", "createdAt", "status", "isActive", "isPending", "type", "extraData" ] }, "AccountTaskExtraDataNeedUserInputDto": { "type": "object", "properties": { "refEmailMessageIds": { "description": "Referenced email message IDs", "example": [ "" ], "type": "array", "items": { "type": "string" } } } }, "AccountTaskNeedUserInputDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "accountId": { "type": "string", "description": "Account ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "title": { "type": "string", "description": "Task title", "example": "Approve new contact eligibility" }, "assignees": { "description": "Assignee user IDs", "example": [ "123e4567-e89b-12d3-a456-426614174003" ], "type": "array", "items": { "type": "string" } }, "thread": { "description": "Task thread of interactions", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/AgentInteractionDto" }, { "$ref": "#/components/schemas/UserInteractionDto" } ] } }, "isClosed": { "type": "boolean", "description": "Whether the task is closed" }, "isCanceled": { "type": "boolean", "description": "Whether the task is canceled" }, "createdAt": { "type": "string", "description": "Task creation timestamp", "example": "2024-05-01T10:15:30.000Z" }, "closedAt": { "type": "object", "description": "Task closed timestamp" }, "canceledAt": { "type": "object", "description": "Task canceled timestamp" }, "cancelReason": { "type": "object", "description": "Why the task was canceled, when a reason was given" }, "status": { "type": "string", "description": "Task status", "enum": [ "Open", "InProgress", "UserActionRequired", "Closed", "Canceled", "Pending" ] }, "isActive": { "type": "boolean", "description": "Whether the task is active" }, "completedAt": { "type": "object", "description": "Task completion timestamp" }, "isPending": { "type": "boolean", "description": "Whether the task is pending" }, "pendingAt": { "type": "object", "description": "Task pending timestamp" }, "type": { "type": "string", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ], "example": "NeedUserInput" }, "extraData": { "description": "Extra data for need user input tasks", "allOf": [ { "$ref": "#/components/schemas/AccountTaskExtraDataNeedUserInputDto" } ] } }, "required": [ "id", "organizationId", "accountId", "title", "assignees", "isClosed", "isCanceled", "createdAt", "status", "isActive", "isPending", "type", "extraData" ] }, "AccountTaskExtraDataPaymentScheduleInvalidatedDto": { "type": "object", "properties": { "invoiceId": { "type": "string", "description": "ID of the replacement invoice the task is about", "example": "123e4567-e89b-12d3-a456-426614174010" }, "invoiceNumber": { "type": "string", "description": "Number of the replacement invoice", "example": "INV-001" }, "previousInvoiceId": { "type": "string", "description": "ID of the previous invoice that was reissued", "example": "123e4567-e89b-12d3-a456-426614174011" }, "previousTotalAmount": { "type": "number", "description": "Total amount of the previous invoice", "example": 100 }, "replacementTotalAmount": { "type": "number", "description": "Total amount of the replacement invoice", "example": 150 }, "previousPaymentSchedule": { "description": "Payment schedule that was active on the previous invoice, no longer applicable to the replacement", "type": "array", "items": { "$ref": "#/components/schemas/account_task_extra_data_dto_PaymentInstallmentDto" } } }, "required": [ "invoiceId", "invoiceNumber", "previousInvoiceId", "previousTotalAmount", "replacementTotalAmount", "previousPaymentSchedule" ] }, "AccountTaskPaymentScheduleInvalidatedDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "accountId": { "type": "string", "description": "Account ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "title": { "type": "string", "description": "Task title", "example": "Approve new contact eligibility" }, "assignees": { "description": "Assignee user IDs", "example": [ "123e4567-e89b-12d3-a456-426614174003" ], "type": "array", "items": { "type": "string" } }, "thread": { "description": "Task thread of interactions", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/AgentInteractionDto" }, { "$ref": "#/components/schemas/UserInteractionDto" } ] } }, "isClosed": { "type": "boolean", "description": "Whether the task is closed" }, "isCanceled": { "type": "boolean", "description": "Whether the task is canceled" }, "createdAt": { "type": "string", "description": "Task creation timestamp", "example": "2024-05-01T10:15:30.000Z" }, "closedAt": { "type": "object", "description": "Task closed timestamp" }, "canceledAt": { "type": "object", "description": "Task canceled timestamp" }, "cancelReason": { "type": "object", "description": "Why the task was canceled, when a reason was given" }, "status": { "type": "string", "description": "Task status", "enum": [ "Open", "InProgress", "UserActionRequired", "Closed", "Canceled", "Pending" ] }, "isActive": { "type": "boolean", "description": "Whether the task is active" }, "completedAt": { "type": "object", "description": "Task completion timestamp" }, "isPending": { "type": "boolean", "description": "Whether the task is pending" }, "pendingAt": { "type": "object", "description": "Task pending timestamp" }, "type": { "type": "string", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ], "example": "PaymentScheduleInvalidated" }, "extraData": { "description": "Extra data for payment schedule invalidated tasks", "allOf": [ { "$ref": "#/components/schemas/AccountTaskExtraDataPaymentScheduleInvalidatedDto" } ] } }, "required": [ "id", "organizationId", "accountId", "title", "assignees", "isClosed", "isCanceled", "createdAt", "status", "isActive", "isPending", "type", "extraData" ] }, "AccountTaskNoticeDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "accountId": { "type": "string", "description": "Account ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "title": { "type": "string", "description": "Task title", "example": "Approve new contact eligibility" }, "assignees": { "description": "Assignee user IDs", "example": [ "123e4567-e89b-12d3-a456-426614174003" ], "type": "array", "items": { "type": "string" } }, "thread": { "description": "Task thread of interactions", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/AgentInteractionDto" }, { "$ref": "#/components/schemas/UserInteractionDto" } ] } }, "isClosed": { "type": "boolean", "description": "Whether the task is closed" }, "isCanceled": { "type": "boolean", "description": "Whether the task is canceled" }, "createdAt": { "type": "string", "description": "Task creation timestamp", "example": "2024-05-01T10:15:30.000Z" }, "closedAt": { "type": "object", "description": "Task closed timestamp" }, "canceledAt": { "type": "object", "description": "Task canceled timestamp" }, "cancelReason": { "type": "object", "description": "Why the task was canceled, when a reason was given" }, "status": { "type": "string", "description": "Task status", "enum": [ "Open", "InProgress", "UserActionRequired", "Closed", "Canceled", "Pending" ] }, "isActive": { "type": "boolean", "description": "Whether the task is active" }, "completedAt": { "type": "object", "description": "Task completion timestamp" }, "isPending": { "type": "boolean", "description": "Whether the task is pending" }, "pendingAt": { "type": "object", "description": "Task pending timestamp" }, "type": { "type": "string", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ], "example": "Notice" }, "extraData": { "description": "Extra data for informative tasks", "allOf": [ { "$ref": "#/components/schemas/AccountTaskExtraDataDto" } ] } }, "required": [ "id", "organizationId", "accountId", "title", "assignees", "isClosed", "isCanceled", "createdAt", "status", "isActive", "isPending", "type", "extraData" ] }, "AccountTaskUnknownDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Task ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174000" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174001" }, "accountId": { "type": "string", "description": "Account ID", "format": "uuid", "example": "123e4567-e89b-12d3-a456-426614174002" }, "title": { "type": "string", "description": "Task title", "example": "Approve new contact eligibility" }, "assignees": { "description": "Assignee user IDs", "example": [ "123e4567-e89b-12d3-a456-426614174003" ], "type": "array", "items": { "type": "string" } }, "thread": { "description": "Task thread of interactions", "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/AgentInteractionDto" }, { "$ref": "#/components/schemas/UserInteractionDto" } ] } }, "isClosed": { "type": "boolean", "description": "Whether the task is closed" }, "isCanceled": { "type": "boolean", "description": "Whether the task is canceled" }, "createdAt": { "type": "string", "description": "Task creation timestamp", "example": "2024-05-01T10:15:30.000Z" }, "closedAt": { "type": "object", "description": "Task closed timestamp" }, "canceledAt": { "type": "object", "description": "Task canceled timestamp" }, "cancelReason": { "type": "object", "description": "Why the task was canceled, when a reason was given" }, "status": { "type": "string", "description": "Task status", "enum": [ "Open", "InProgress", "UserActionRequired", "Closed", "Canceled", "Pending" ] }, "isActive": { "type": "boolean", "description": "Whether the task is active" }, "completedAt": { "type": "object", "description": "Task completion timestamp" }, "isPending": { "type": "boolean", "description": "Whether the task is pending" }, "pendingAt": { "type": "object", "description": "Task pending timestamp" }, "type": { "type": "string", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ], "example": "Unknown" }, "extraData": { "description": "Extra data for unknown tasks", "allOf": [ { "$ref": "#/components/schemas/AccountTaskExtraDataDto" } ] } }, "required": [ "id", "organizationId", "accountId", "title", "assignees", "isClosed", "isCanceled", "createdAt", "status", "isActive", "isPending", "type", "extraData" ] }, "AgentInfoDto": { "type": "object", "properties": { "email": { "type": "string", "description": "Agent email address", "example": "agent@billabex.com" }, "firstName": { "type": "string", "description": "Agent first name", "example": "Alex" }, "lastName": { "type": "string", "description": "Agent last name", "example": "Martin" } }, "required": [ "email", "firstName", "lastName" ] }, "AgentInteractionDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique interaction ID", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "message": { "description": "Message content for the interaction", "oneOf": [ { "$ref": "#/components/schemas/InteractionMessageTextDto" }, { "$ref": "#/components/schemas/InteractionMessageStructuredDto" } ] }, "attachments": { "description": "Attachment filestore IDs", "example": [ "filestore_123" ], "type": "array", "items": { "type": "string" } }, "sentAt": { "type": "string", "description": "Interaction send time (ISO 8601)", "example": "2024-05-01T10:15:30.000Z" }, "agent": { "description": "Agent info for this interaction", "allOf": [ { "$ref": "#/components/schemas/AgentInfoDto" } ] } }, "required": [ "id", "message", "attachments", "sentAt", "agent" ] }, "UserInteractionDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique interaction ID", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "message": { "description": "Message content for the interaction", "oneOf": [ { "$ref": "#/components/schemas/InteractionMessageTextDto" }, { "$ref": "#/components/schemas/InteractionMessageStructuredDto" } ] }, "attachments": { "description": "Attachment filestore IDs", "example": [ "filestore_123" ], "type": "array", "items": { "type": "string" } }, "sentAt": { "type": "string", "description": "Interaction send time (ISO 8601)", "example": "2024-05-01T10:15:30.000Z" }, "userId": { "type": "string", "description": "User ID of the interaction author", "example": "123e4567-e89b-12d3-a456-426614174001", "format": "uuid" }, "userFullName": { "type": "string", "description": "User full name", "example": "Jane Doe" } }, "required": [ "id", "message", "attachments", "sentAt", "userId" ] }, "AccountTaskResponseDto": { "type": "object", "properties": { "task": { "oneOf": [ { "$ref": "#/components/schemas/AccountTaskApproveEligibilityDto" }, { "$ref": "#/components/schemas/AccountTaskApproveContactChangeDto" }, { "$ref": "#/components/schemas/AccountTaskNeedContactsDto" }, { "$ref": "#/components/schemas/AccountTaskAskNextActionDto" }, { "$ref": "#/components/schemas/AccountTaskApproveFirstOutreachDto" }, { "$ref": "#/components/schemas/AccountTaskApprovePaymentArrangementDto" }, { "$ref": "#/components/schemas/AccountTaskNeedUserInputDto" }, { "$ref": "#/components/schemas/AccountTaskPaymentScheduleInvalidatedDto" }, { "$ref": "#/components/schemas/AccountTaskNoticeDto" }, { "$ref": "#/components/schemas/AccountTaskUnknownDto" } ] } }, "required": [ "task" ] }, "AccountTaskListItemDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Account task ID", "format": "uuid" }, "organizationId": { "type": "string", "description": "Organization ID", "format": "uuid" }, "accountId": { "type": "string", "description": "Account ID", "format": "uuid" }, "accountFullName": { "type": "string", "description": "Account full name" }, "accountTagIds": { "description": "Tag IDs of the account", "type": "array", "items": { "type": "string" } }, "title": { "type": "string", "description": "Task title" }, "type": { "type": "string", "description": "Task type", "enum": [ "ApproveEligibility", "ApproveContactChange", "ApprovePaymentArrangement", "NeedContacts", "AskNextAction", "ApproveFirstOutreach", "NeedUserInput", "PaymentScheduleInvalidated", "Notice", "Unknown" ] }, "status": { "type": "string", "description": "Task status", "enum": [ "Open", "InProgress", "UserActionRequired", "Closed", "Canceled", "Pending" ] }, "assignees": { "description": "User IDs the task is assigned to", "type": "array", "items": { "type": "string" } }, "assigneesFullName": { "description": "Full names of the assignees", "type": "array", "items": { "type": "string" } }, "isClosed": { "type": "boolean", "description": "Whether the task is closed" }, "isCanceled": { "type": "boolean", "description": "Whether the task is canceled" }, "isPending": { "type": "boolean", "description": "Whether the task waits for a user answer" }, "isActive": { "type": "boolean", "description": "Whether the task is still active" }, "balance": { "type": "object", "description": "Outstanding balance of the account", "nullable": true }, "currency": { "type": "object", "description": "Currency of the balance", "nullable": true }, "createdAt": { "type": "string", "description": "Creation date", "format": "date-time" }, "updatedAt": { "type": "string", "description": "Last update date", "format": "date-time" }, "closedAt": { "type": "object", "description": "Closing date", "format": "date-time", "nullable": true }, "canceledAt": { "type": "object", "description": "Cancellation date", "format": "date-time", "nullable": true }, "cancelReason": { "type": "object", "description": "Why the task was canceled, when a reason was given", "nullable": true }, "pendingAt": { "type": "object", "description": "Date the task started waiting for a user answer", "format": "date-time", "nullable": true }, "completedAt": { "type": "object", "description": "Completion date", "format": "date-time", "nullable": true }, "lastAgentInteractionAt": { "type": "string", "description": "Date of the last agent interaction", "format": "date-time" } }, "required": [ "id", "organizationId", "accountId", "accountFullName", "accountTagIds", "title", "type", "status", "assignees", "assigneesFullName", "isClosed", "isCanceled", "isPending", "isActive", "balance", "currency", "createdAt", "updatedAt", "closedAt", "canceledAt", "cancelReason", "pendingAt", "completedAt", "lastAgentInteractionAt" ] }, "PageInfoDto": { "type": "object", "properties": { "endCursor": { "type": "string", "description": "Cursor pointing to the last item of the current page", "example": "YXJyYXljb25uZWN0aW9uOjEx" } } }, "PaginatedAccountTaskListResponseDto": { "type": "object", "properties": { "nodes": { "description": "Account tasks", "type": "array", "items": { "$ref": "#/components/schemas/AccountTaskListItemDto" } }, "pageInfo": { "description": "Pagination information", "allOf": [ { "$ref": "#/components/schemas/PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "CancelAccountTaskDto": { "type": "object", "properties": { "reason": { "type": "string", "description": "Why the task is being cancelled. Optional here so existing callers keep working, but recorded and shown next to the cancellation whenever it is provided.", "maxLength": 2000, "example": "Invoice re-sent by hand, the contact confirmed reception." } } }, "InteractionMessageStructuredDto": { "type": "object", "properties": { "type": { "type": "string", "description": "Message type", "enum": [ "Text", "Structured" ], "example": "Structured" }, "schema": { "type": "string", "description": "Structured schema name", "example": "ApproveEligibility" }, "schemaVersion": { "type": "number", "description": "Structured schema version", "example": 1 }, "value": { "type": "object", "description": "Structured JSON value payload", "example": true } }, "required": [ "type", "schema", "schemaVersion", "value" ] }, "InteractionMessageTextDto": { "type": "object", "properties": { "type": { "type": "string", "description": "Message type", "enum": [ "Text", "Structured" ], "example": "Text" }, "value": { "type": "string", "description": "Plain text message content", "example": "Yes, please proceed with the approval." } }, "required": [ "type", "value" ] }, "AddAccountTaskTextInteractionDto": { "type": "object", "properties": { "attachments": { "description": "Attachments for the interaction", "example": [ "filestore_123" ], "type": "array", "items": { "type": "string" } }, "message": { "description": "Text message content", "oneOf": [ { "$ref": "#/components/schemas/InteractionMessageTextDto" } ], "example": { "type": "Text", "value": "Here are the requested details." }, "allOf": [ { "$ref": "#/components/schemas/InteractionMessageTextDto" } ] } }, "required": [ "message" ] }, "AddAccountTaskStructuredInteractionDto": { "type": "object", "properties": { "attachments": { "description": "Attachments for the interaction", "example": [ "filestore_123" ], "type": "array", "items": { "type": "string" } }, "message": { "description": "Structured message content", "oneOf": [ { "$ref": "#/components/schemas/InteractionMessageStructuredDto" } ], "example": { "type": "Structured", "schema": "ApproveEligibility", "schemaVersion": 1, "value": true }, "allOf": [ { "$ref": "#/components/schemas/InteractionMessageStructuredDto" } ] } }, "required": [ "message" ] }, "AddAccountTaskInteractionEnvelopeDto": { "type": "object", "properties": { "interaction": { "oneOf": [ { "$ref": "#/components/schemas/AddAccountTaskTextInteractionDto" }, { "$ref": "#/components/schemas/AddAccountTaskStructuredInteractionDto" } ] } }, "required": [ "interaction" ] }, "InteractionResponseDto": { "type": "object", "properties": { "interaction": { "oneOf": [ { "$ref": "#/components/schemas/AgentInteractionDto" }, { "$ref": "#/components/schemas/UserInteractionDto" } ] } }, "required": [ "interaction" ] }, "EmailWithTypeResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the email (UUID v4)", "example": "123e4567-e89b-12d3-a456-426614174000", "format": "uuid" }, "type": { "type": "string", "description": "Type of email (incoming or outgoing)", "enum": [ "IncomingEmail", "OutgoingEmail" ], "example": "OutgoingEmail" }, "from": { "description": "Sender email address", "allOf": [ { "$ref": "#/components/schemas/EmailAddressResponseDto" } ] }, "to": { "type": "array", "items": { "description": "List of recipient email addresses", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressResponseDto" } } }, "cc": { "type": "array", "items": { "description": "List of CC recipient email addresses", "type": "array", "items": { "$ref": "#/components/schemas/EmailAddressResponseDto" } } }, "subject": { "type": "string", "description": "Email subject", "example": "Invoice reminder - INV-2024-001" }, "body": { "description": "Email body content", "allOf": [ { "$ref": "#/components/schemas/EmailBodyResponseDto" } ] }, "inReplyTo": { "type": "string", "description": "Message ID of the email being replied to", "example": "", "nullable": true }, "references": { "description": "List of message IDs in the email thread", "items": { "type": "array", "items": { "type": "string" } }, "type": "array" }, "attachments": { "description": "List of attachment file IDs", "items": { "type": "array", "items": { "type": "string" } }, "type": "array" } }, "required": [ "id", "type", "from", "to", "cc", "subject", "body", "inReplyTo", "references", "attachments" ] }, "paginated_response_dto_PageInfoDto": { "type": "object", "properties": { "endCursor": { "type": "string", "description": "Cursor to use for fetching the next page", "example": "eyJpZCI6IjEyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMCJ9" } } }, "PaginatedEmailsResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "description": "List of emails", "type": "array", "items": { "$ref": "#/components/schemas/EmailWithTypeResponseDto" } } }, "pageInfo": { "description": "Pagination info", "allOf": [ { "$ref": "#/components/schemas/paginated_response_dto_PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "PaginatedOutgoingEmailsResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "description": "List of outgoing emails", "type": "array", "items": { "$ref": "#/components/schemas/OutgoingEmailResponseDto" } } }, "pageInfo": { "description": "Pagination info", "allOf": [ { "$ref": "#/components/schemas/paginated_response_dto_PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "PaginatedIncomingEmailsResponseDto": { "type": "object", "properties": { "nodes": { "type": "array", "items": { "description": "List of incoming emails", "type": "array", "items": { "$ref": "#/components/schemas/IncomingEmailResponseDto" } } }, "pageInfo": { "description": "Pagination info", "allOf": [ { "$ref": "#/components/schemas/paginated_response_dto_PageInfoDto" } ] } }, "required": [ "nodes", "pageInfo" ] }, "ApiError": { "type": "object", "description": "Structured JSON error returned by the Billabex API.", "required": [ "message", "code", "frontMessage", "timestamp", "path", "type", "method" ], "properties": { "message": { "type": "string", "description": "Technical error message, including the corrective action when applicable.", "example": "Invalid or missing OAuth token" }, "code": { "type": "string", "description": "Stable machine-readable error code.", "example": "HTTP_401" }, "frontMessage": { "type": "string", "description": "Localization key for the user-facing error message.", "example": "api.globalExceptionCode.Unknown" }, "timestamp": { "type": "string", "format": "date-time" }, "path": { "type": "string", "example": "/api/public/v1/organizations" }, "type": { "type": "string", "example": "http" }, "method": { "type": "string", "example": "GET" } } } } }, "x-tagGroups": [ { "name": "Invoicing", "tags": [ "invoices", "credit-notes", "accounts", "contacts", "credit-allocations", "source" ] }, { "name": "Dunning", "tags": [ "communications", "incoming-email-communications", "outgoing-email-communications", "customer-outstanding-balances" ] }, { "name": "Email", "tags": [ "emails", "incoming-emails", "outgoing-emails" ] }, { "name": "Tasking", "tags": [ "account-tasks" ] }, { "name": "Platform", "tags": [ "organizations" ] }, { "name": "Other", "tags": [ "tags", "user-profile", "outgoing-letters", "outgoing-message-communications" ] } ], "externalDocs": { "description": "Billabex developer documentation", "url": "https://developer.billabex.com/" }, "x-source": "https://next.billabex.com/api/docs/public-json", "x-oauth-authorization-server-metadata": "https://next.billabex.com/.well-known/oauth-authorization-server", "x-oauth-protected-resource-metadata": "https://next.billabex.com/.well-known/oauth-protected-resource" }