OpenAPI definition (preview)
This article contains the OpenAPI definition file for setting up the necessary API endpoints for Copilot For Finance in the custom connector.
[This article is prerelease documentation and is subject to change.]
openapi: 3.0.0
info:
title: Copilot for Finance / Customer communications
version: 2024.06.20
tags:
- name: API version
- name: Contacts
- name: Customers.
- name: Outstanding invoices.
paths:
/contacts:
post:
tags:
- Contacts
operationId: Contacts_list
summary: List of contacts
description: "One of the parameters email or/and phone number must be provided. Parameters work together as 'OR' condition. For example: emails=['email1', 'email2'] phoneNumbers=['phone1','phone2'] retrieves all contacts with rather email1 or email2 or phone1 or phone2."
parameters:
- name: x-copilotforfinace-api-version
in: header
required: true
description: Specifies the API version.
schema:
type: string
- name: language
in: query
required: false
description: The language code is in BCP 47 format.
schema:
type: string
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/Contact'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactInfoRequest'
/contacts/create:
post:
tags:
- Contacts
operationId: Contacts_create
summary: Creates contact
description: Creates contact.
parameters:
- name: x-copilotforfinace-api-version
in: header
required: true
description: Specifies the API version.
schema:
type: string
- name: language
in: query
required: false
description: The language code is in BCP 47 format.
schema:
type: string
responses:
'201':
description: Creates the contact and returns the contact object.
content:
application/json:
schema:
$ref: '#/components/schemas/ContactForUpdateResponse'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactForUpdate'
/contacts/{contactId}:
put:
tags:
- Contacts
operationId: Contacts_update
summary: Updates contact
description: Updates contact.
parameters:
- name: x-copilotforfinace-api-version
in: header
required: true
description: Specifies the API version.
schema:
type: string
- name: contactId
in: path
required: true
schema:
type: string
- name: language
in: query
required: false
description: The language code is in BCP 47 format.
schema:
type: string
responses:
'201':
description: The request has succeeded and a new resource has been created as a result.
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactForUpdate'
/customers:
post:
tags:
- Customers.
operationId: Customers_list
summary: List of customers
description: The 'Customers' endpoint without customers ids specified returns list of all customers.
parameters:
- name: x-copilotforfinace-api-version
in: header
required: true
description: Specifies the API version.
schema:
type: string
- name: organizationCode
in: query
required: false
schema:
type: string
- name: accountNumber
in: query
required: false
schema:
type: string
- name: name
in: query
required: false
schema:
type: string
- name: industryName
in: query
required: false
schema:
type: string
- name: language
in: query
required: false
description: The language code is in BCP 47 format.
schema:
type: string
- name: top
in: query
required: false
schema:
type: integer
format: int32
- name: skip
in: query
required: false
schema:
type: integer
format: int32
- name: filter
in: query
required: false
description: "Format for using the 'filter' is as follows: filter=contains(fieldName,'substring') or contains(fieldName2,'substring2) etc. Applicable fields: name, organizationCode, accountNumber, industryName."
schema:
type: string
- name: orderby
in: query
required: false
description: 'Format: orderby=fieldName:asc or orderby=fieldName:desc. Applicable for all fields.'
schema:
type: string
- name: select
in: query
required: false
description: "The 'select' parameter is used to retrieve only the specified fields from the collection. Format: select=id,name,accountNumber."
schema:
type: string
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/Customer'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerIds'
/customers/{customerId}/accountstatement:
get:
tags:
- Customers.
operationId: Customers_accountStatement
summary: Returns the account statement for a given customer
description: Returns the account statement for a given customer. You could provide a custom file name for the document by setting the 'Content-Disposition' header. If there is no file name is provided, default file name would be assigned. The 'Content-Type' header should be set to 'application/pdf'.
parameters:
- name: x-copilotforfinace-api-version
in: header
required: true
description: Specifies the API version.
schema:
type: string
- name: customerId
in: path
required: true
schema:
type: string
- name: language
in: query
required: false
description: The language code is in BCP 47 format.
schema:
type: string
responses:
'200':
description: The request has succeeded.
headers:
Content-Type:
required: false
schema:
type: string
enum:
- application/pdf
- application/zip
Content-Disposition:
required: false
schema:
type: string
content:
application/pdf:
schema:
type: string
format: binary
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/customers/{customerId}/activities:
get:
tags:
- Customers.
operationId: Customers_activities
summary: Customer related activities
description: Returns customer related activities.
parameters:
- name: x-copilotforfinace-api-version
in: header
required: true
description: Specifies the API version.
schema:
type: string
- name: customerId
in: path
required: true
schema:
type: string
- name: id
in: query
required: false
schema:
type: string
- name: title
in: query
required: false
schema:
type: string
- name: type
in: query
required: false
schema:
type: string
- name: text
in: query
required: false
schema:
type: string
- name: timeStamp
in: query
required: false
schema:
type: string
- name: language
in: query
required: false
description: The language code is in BCP 47 format.
schema:
type: string
- name: top
in: query
required: false
schema:
type: integer
format: int32
- name: skip
in: query
required: false
schema:
type: integer
format: int32
- name: filter
in: query
required: false
description: "Format for using the 'filter' is as follows: filter=contains(fieldName,'substring') or contains(fieldName2,'substring2) or filter=contains(fieldName,'substring') and contains(fieldName2,'substring2). Applicable for all fields."
schema:
type: string
- name: range
in: query
required: false
description: |-
Format: range=fieldName:'value_min':'value_max' Dates are in UTC.
Applicable to fields of type date or amount.
schema:
type: string
- name: orderby
in: query
required: false
description: 'Format: orderby=fieldName:asc or orderby=fieldName:desc. Applicable for all fields.'
schema:
type: string
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomerActivity'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/customers/{customerId}/agedbalances:
get:
tags:
- Customers.
operationId: Customers_agedBalances
summary: Returns aged balances for a given customer
description: Returns aged balances for a given customer.
parameters:
- name: x-copilotforfinace-api-version
in: header
required: true
description: Specifies the API version.
schema:
type: string
- name: customerId
in: path
required: true
schema:
type: string
- name: language
in: query
required: false
description: The language code is in BCP 47 format.
schema:
type: string
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/AgedBalance'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/customers/{customerId}/invoicedocuments:
post:
tags:
- Customers.
operationId: Customers_invoiceDocument
summary: Returns invoice documents
description: Get invoice documents. If Request body is empty, it will return all the documents for the customer in zip archive. If Request body contains invoiceIds, it will return the documents for the specified customer and invoice ids in zip archive for multiple invoices and in pdf for a single invoice. The 'Content-Type' header should be set to 'application/pdf' or 'application/zip'. You could provide a custom file name for the document by setting the 'Content-Disposition' header. If there is no file name is provided, default file name would be assigned.
parameters:
- name: x-copilotforfinace-api-version
in: header
required: true
description: Specifies the API version.
schema:
type: string
- name: customerId
in: path
required: true
schema:
type: string
- name: language
in: query
required: false
description: The language code is in BCP 47 format.
schema:
type: string
responses:
'200':
description: The request has succeeded.
headers:
Content-Type:
required: false
schema:
type: string
enum:
- application/pdf
- application/zip
Content-Disposition:
required: false
schema:
type: string
content:
application/pdf:
schema:
type: string
format: binary
application/zip:
schema:
type: string
format: binary
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceDocumentRequest'
/customers/{customerId}/invoices:
get:
tags:
- Customers.
operationId: Customers_invoices
summary: Returns list of invoices for a given customer
description: 'Returns invoices that are relevant for a collections coordinator: open, unpaid, and outstanding invoices.'
parameters:
- name: x-copilotforfinace-api-version
in: header
required: true
description: Specifies the API version.
schema:
type: string
- name: customerId
in: path
required: true
schema:
type: string
- name: id
in: query
required: false
schema:
type: string
- name: status
in: query
required: false
schema:
type: string
- name: transactionType
in: query
required: false
schema:
type: string
- name: voucher
in: query
required: false
schema:
type: string
- name: invoiceNumber
in: query
required: false
schema:
type: string
- name: organizationCode
in: query
required: false
schema:
type: string
- name: dueDate
in: query
required: false
schema:
type: string
- name: transactionDate
in: query
required: false
schema:
type: string
- name: transactionAmount
in: query
required: false
schema:
type: string
- name: currency
in: query
required: false
schema:
type: string
- name: language
in: query
required: false
description: The language code is in BCP 47 format.
schema:
type: string
- name: top
in: query
required: false
schema:
type: integer
format: int32
- name: skip
in: query
required: false
schema:
type: integer
format: int32
- name: filter
in: query
required: false
description: "Format for using the 'filter' is as follows: filter=contains(fieldName,'substring') or contains(fieldName2,'substring2) or filter=contains(fieldName,'substring') and contains(fieldName2,'substring2). Applicable for all fields except the id."
schema:
type: string
- name: range
in: query
required: false
description: |-
Format: range=fieldName:'value_min':'value_max' Dates are in UTC.
Applicable to fields of type date or amount.
schema:
type: string
- name: orderby
in: query
required: false
description: 'Format: orderby=fieldName:asc or orderby=fieldName:desc. Applicable for all fields.'
schema:
type: string
- name: select
in: query
required: false
description: 'Format: select=fieldName1,fieldName2,fieldName3.'
schema:
type: string
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/Invoice'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/invoices/statuses:
get:
tags:
- Outstanding invoices.
operationId: Invoices_listOfStatuses
summary: Returns list of statuses
description: List of all possible statuses for an invoice.
parameters:
- name: x-copilotforfinace-api-version
in: header
required: true
description: Specifies the API version.
schema:
type: string
- name: language
in: query
required: false
description: The language code is in BCP 47 format.
schema:
type: string
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: array
items:
$ref: '#/components/schemas/StatusDefinition'
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/invoices/{invoiceId}/status:
put:
tags:
- Outstanding invoices.
operationId: Invoices_updateStatus
summary: Updates invoice status and promised to pay date
description: Updates invoice status and promised to pay date.
parameters:
- name: x-copilotforfinace-api-version
in: header
required: true
description: Specifies the API version.
schema:
type: string
- name: invoiceId
in: path
required: true
schema:
type: string
- name: language
in: query
required: false
description: The language code is in BCP 47 format.
schema:
type: string
responses:
'201':
description: The request has succeeded and a new resource has been created as a result.
default:
description: An unexpected error response.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceStatus'
/version:
get:
tags:
- API version
operationId: Version_supportedVersion
summary: API version
description: Returns the latest supported version of the API. This value will be used in the x-copilotforfinance-api-version header for subsequent requests to ensure Copilot for Finance calls a supported version of your API. The version value can be find on the top of OpenAPI specification file. For example, 2024.06.20.
parameters: []
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
type: string
components:
schemas:
AdditionalParameters:
type: object
properties:
Pagination:
$ref: '#/components/schemas/PaginationParameters'
Filter:
$ref: '#/components/schemas/Filter'
Range:
$ref: '#/components/schemas/Range'
OrderBy:
$ref: '#/components/schemas/OrderBy'
Address:
type: object
required:
- street
- city
- country
properties:
street:
type: string
city:
type: string
country:
type: string
AgedBalance:
type: object
required:
- id
- name
- totalAmountDue
- agingDate
- agingPeriods
properties:
id:
type: string
name:
type: string
isDefault:
type: boolean
totalAmountDue:
type: number
format: decimal
agingDate:
type: string
format: date-time
currency:
type: string
totalOverdueInvoices:
type: integer
agingPeriods:
type: array
items:
$ref: '#/components/schemas/AgingPeriod'
description: 'The dates are in UTC format. Example: 2021-01-01T00:00:00Z. The amounts are in decimal format and are converted into user locale formats automatically on the frontend side.'
AgingPeriod:
type: object
required:
- label
- amount
properties:
label:
type: string
amount:
type: number
format: decimal
Contact:
type: object
required:
- id
- email
- firstName
- lastName
- customerId
- customerName
properties:
id:
type: string
email:
type: string
firstName:
type: string
lastName:
type: string
professionalTitle:
type: string
organizationCode:
type: string
customerId:
type: string
customerName:
type: string
primaryPhoneNumber:
type: string
ContactForUpdate:
type: object
required:
- email
- firstName
- lastName
- customerId
properties:
email:
type: string
firstName:
type: string
lastName:
type: string
professionalTitle:
type: string
customerId:
type: string
primaryPhoneNumber:
type: string
ContactForUpdateResponse:
type: object
required:
- id
- email
- firstName
- lastName
- customerId
properties:
id:
type: string
email:
type: string
firstName:
type: string
lastName:
type: string
professionalTitle:
type: string
customerId:
type: string
primaryPhoneNumber:
type: string
ContactInfoRequest:
type: object
properties:
emails:
type: array
items:
type: string
phoneNumbers:
type: array
items:
type: string
Customer:
type: object
required:
- id
- name
- accountNumber
properties:
id:
type: string
name:
type: string
organizationCode:
type: string
accountNumber:
type: string
industryName:
type: string
address:
$ref: '#/components/schemas/Address'
CustomerActivity:
type: object
required:
- id
- title
- text
properties:
id:
type: string
title:
type: string
text:
type: string
type:
type: string
timeStamp:
type: string
format: date-time
description: 'The dates are in UTC format. Example: 2021-01-01T00:00:00Z. The amounts are in decimal format and are converted into user locale formats automatically on the frontend side.'
CustomerIds:
type: object
required:
- customerIds
properties:
customerIds:
type: array
items:
type: string
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
Filter:
type: object
properties:
filter:
type: string
description: |-
The 'filter' is designed to fetch records where a specified field contains a particular substring. The filter supports either 'or' or 'and' logical operators, but not both in the same filter.
The format for using the 'filter' is as follows: filter=contains(fieldName,'substring') or contains(fieldName2,'substring2) or filter=contains(fieldName,'substring') and contains(fieldName2,'substring2).
For example:
1. /customers?filter=contains(name,'Contoso') and contains(organizationcode,'US') retrieves all records where the customer name contains the 'Contoso' substring ans organization code contains 'US.
2. /customers?filter=contains(name,'Contoso') or contains(organizationcode,'contoso') retrieves all records where the customer name contains the 'Contoso' substring or organization code contains 'Contoso'.
Invoice:
type: object
required:
- id
- voucher
- transactionDate
- transactionAmount
- invoiceNumber
- dueDate
- currency
- transactionType
- hasDocument
properties:
id:
type: string
voucher:
type: string
transactionDate:
type: string
format: date-time
transactionAmount:
type: number
format: decimal
invoiceNumber:
type: string
dueDate:
type: string
format: date-time
currency:
type: string
transactionType:
type: string
hasDocument:
type: boolean
statusId:
type: string
statusName:
type: string
promiseToPayDate:
type: string
format: date-time
statusReason:
type: string
statusComment:
type: string
description: 'The dates are in UTC format. Example: 2021-01-01T00:00:00Z. The amounts are in decimal format and are converted into user locale formats automatically on the frontend side.'
InvoiceDocumentRequest:
type: object
required:
- invoiceIds
properties:
invoiceIds:
type: array
items:
type: string
InvoiceStatus:
type: object
required:
- statusId
- statusName
properties:
statusId:
type: string
statusName:
type: string
promiseToPayDate:
type: string
format: date-time
statusReason:
type: string
statusComment:
type: string
description: 'The dates are in UTC format. Example: 2021-01-01T00:00:00Z. The amounts are in decimal format and are converted into user locale formats automatically on the frontend side.'
OrderBy:
type: object
properties:
orderby:
type: string
description: "The orderby parameter is used to sort the results based on the specified field and sorting direction. The format for using the 'orderby' parameter is as follows: orderby=fieldName:asc or orderby=fieldName:desc. For example: /customers?orderby=transactionDate:asc sorts the results based on the transaction date field in ascending order."
PaginationParameters:
type: object
properties:
top:
type: integer
format: int32
skip:
type: integer
format: int32
description: |-
The parameter 'top' defines the maximum number of resources to be retrieved from the collection.
The parameter 'skip' indicates the offset within the collection of the first resource to be returned.
Range:
type: object
properties:
range:
type: string
description: "The 'range' filter is expected to retrieve records where the specified field is within the specified range. The format for using the 'range' filter is as follows: range=fieldName:'value_min':'value_max'. Applicable for all dates and amounts related fields. For example: /customers?range=totalOverdueInvoices:1:5 retrieves all records where the total overdue invoices field is more than 1 and less than 5."
Select:
type: object
properties:
select:
type: string
description: "The 'select' parameter is used to retrieve only the specified fields from the collection. The format for using the 'select' parameter is as follows: select=fieldName1,fieldName2,fieldName3. For example: /customers?select=name,organizationCode retrieves only the name and organization code fields from the collection."
StatusDefinition:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
Versions:
type: string
enum:
- 2024.06.20