# Avalara E-Invoicing API

An API that supports sending data for an E-Invoicing compliance use-case.

Source: https://developer.avalara.com/products/e-invoicing/api/

**Version:** 1.1
**Base URL:** https://api.sbx.avalara.com/einvoicing

---

## Endpoints

### Documents

#### Returns a summary of documents for a date range

`GET /documents`

Get a list of documents on the Avalara E-Invoicing platform that have a processing date within the specified date range.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a fingerprint. |
| `startDate` | string | query | No | Start date of documents to return. This defaults to the previous month. |
| `endDate` | string | query | No | End date of documents to return. This defaults to the current date. |
| `flow` | string | query | No | Optionally filter by document direction, where issued = `out` and received = `in` |
| `$count` | string | query | No | When set to true, the count of the collection is also returned in the response body |
| `$countOnly` | string | query | No | When set to true, only the count of the collection is returned |
| `$filter` | string | query | No | Filter by field name and value. This filter only supports eq . Refer to [https://developer.avalara.com/avatax/filtering-in-rest/](https://developer.avalara.com/avatax/filtering-in-rest/) for more information on filtering. Filtering will be done over the provided startDate and endDate. If no startDate or endDate is provided, defaults will be assumed. |
| `$top` | string | query | No | If nonzero, return no more than this number of results. Used with $skip to provide pagination for large datasets. Unless otherwise specified, the maximum number of records that can be returned from an API call is 200 records. |
| `$skip` | string | query | No | If nonzero, skip this number of results before returning data. Used with $top to provide pagination for large datasets. |

#### Submits a document to Avalara E-Invoicing API

`POST /documents`

When a UBL document is sent to this endpoint, it generates a document in the required format as mandated by the specified country. Additionally, it initiates the workflow to transmit the generated document to the relevant tax authority, if necessary.The response from the endpoint contains a unique document ID, which can be used to request the status of the document and verify if it was successfully accepted at the destination.Furthermore, the unique ID enables the download of a copy of the generated document for reference purposes.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a fingerprint. |

#### Returns a copy of the document

`GET /documents/{documentId}/$download`

When the document is available, use this endpoint to download it as text, XML, or PDF. The output format needs to be specified in the Accept header, and it will vary depending on the mandate. If the file has not yet been created, then status code 404 (not found) is returned.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `Accept` | string | header | Yes | This header indicates the MIME type of the document |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a fingerprint. |
| `documentId` |  | path | Yes | The unique ID for this document that was returned in the POST /einvoicing/document response body |

#### Checks the status of a document

`GET /documents/{documentId}/status`

Using the unique ID from POST /einvoicing/documents response body, request the current status of a document.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a fingerprint. |
| `documentId` |  | path | Yes | The unique ID for this document that was returned in the POST /einvoicing/documents response body |

#### Fetch the inbound document from a tax authority

`POST /documents/$fetch`

This API allows you to retrieve an inbound document. Pass key-value pairs as parameters in the request, such as the confirmation number, supplier number, and buyer VAT number.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a fingerprint. |


### Data Input Fields

#### Returns the optionality of document fields for different country mandates

`GET /data-input-fields`

This endpoint provides a list of required, conditional, and optional fields for each country mandate. You can use the mandates endpoint to retrieve all available country mandates. You can use the $filter query parameter to retrieve fields for a particular mandate

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a fingerprint. |
| `$filter` | string | query | No | Filter by field name and value. This filter only supports eq and contains. Refer to [https://developer.avalara.com/avatax/filtering-in-rest/](https://developer.avalara.com/avatax/filtering-in-rest/) for more information on filtering. |
| `$top` | string | query | No | If nonzero, return no more than this number of results. Used with $skip to provide pagination for large datasets. Unless otherwise specified, the maximum number of records that can be returned from an API call is 1,000 records. |
| `$skip` | string | query | No | If nonzero, skip this number of results before returning data. Used with $top to provide pagination for large datasets. |
| `$count` | string | query | No | When set to true, the count of the collection is also returned in the response body |
| `$countOnly` | string | query | No | When set to true, only the count of the collection is returned |


### Mandates

#### List country mandates that are supported by the Avalara E-Invoicing platform

`GET /mandates`

This endpoint offers a list of country mandates supported by the Avalara E-Invoicing API.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a fingerprint. |
| `$filter` | string | query | No | Filter by field name and value. This filter only supports eq and contains. Refer to [https://developer.avalara.com/avatax/filtering-in-rest/](https://developer.avalara.com/avatax/filtering-in-rest/) for more information on filtering. |
| `$top` | string | query | No | If nonzero, return no more than this number of results. Used with $skip to provide pagination for large datasets. Unless otherwise specified, the maximum number of records that can be returned from an API call is 1,000 records. |
| `$skip` | string | query | No | If nonzero, skip this number of results before returning data. Used with $top to provide pagination for large datasets. |
| `$count` | string | query | No | When set to true, the count of the collection is also returned in the response body. |
| `$countOnly` | string | query | No | When set to true, only the count of the collection is returned |

#### Returns document field information for a country mandate, a selected document type, and its version

`GET /mandates/{mandateId}/data-input-fields`

This endpoint provides document field details and the optionality of fields (required, conditional, optional) of different documents supported by the country mandate. Use the GET /mandates endpoint to retrieve all available country mandates, their supported document types and supported versions. You can use the `documentType` and `documentVersion` query parameters to retrieve the input fields for a particular document type and document version.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | The HTTP Header meant to specify the version of the API intended to be used |
| `X-Avalara-Client` | string | header | No | You can freely use any text you wish for this value. This feature can help you diagnose and solve problems with your software. The header can be treated like a fingerprint. |
| `mandateId` | string | path | Yes | The unique ID for the mandate that was returned in the GET /einvoicing/mandates response body |
| `documentType` | string | query | Yes | Select the documentType for which you wish to view the data-input-fields (You may obtain the supported documentTypes from the GET /mandates endpoint) |
| `documentVersion` | string | query | Yes | Select the document version of the documentType (You may obtain the supported documentVersion from the GET /mandates endpoint) |

---

## Models

### documentId

The unique ID for this document that was returned in the POST /einvoicing/documents response body. This is a UID created by the Avalara E-Invoicing platform.

### documentFetch

An object of the inbound document

| Property | Type | Description |
|---|---|---|
| `id` | string | Unique ID for this document that can be used for status checking and file downloads. This is a UID created by the Avalara E-Invoicing platform. |
| `status` | string | Status of the document |
| `eventDateTime` | string | The date and time when the inbound document was accepted by the Avalara E-Invoicing Platform |

### DocumentSubmitResponse

Returns the unique ID of a successful document submission

| Property | Type | Description |
|---|---|---|
| `id` | string | Unique ID for this document that can be used for status checking and file downloads. This is a UID created by the Avalara E-Invoicing platform. |

### DocumentStatusResponse

Returns the current document ID and status

| Property | Type | Description |
|---|---|---|
| `id` | string | The unique ID for this document |
| `status` | string | Status of the document |
| `events` | array |  |

### DocumentListResponse

Returns the requested list of documents

| Property | Type | Description |
|---|---|---|
| `@recordsetCount` | string | Count of collections for the given date range |
| `@nextLink` | string |  |
| `value` | array | Array of documents matching query parameters |

### DocumentSummary

Displays a summary of information about the document

| Property | Type | Description |
|---|---|---|
| `id` | string | The unique ID for this document |
| `companyId` | string | Unique identifier that represents the company within the system. |
| `processDateTime` | string | The date and time when the document was processed, displayed in the format YYYY-MM-DDThh:mm:ss |
| `status` | string | The Document status |
| `supplierName` | string | The name of the supplier in the transaction |
| `customerName` | string | The name of the customer in the transaction |
| `documentType` | string | The document type |
| `documentVersion` | string | The document version |
| `documentNumber` | string | The document number |
| `documentDate` | string | The document issue date |
| `flow` | string | The document direction, where issued = `out` and received = `in` |
| `countryCode` | string | The two-letter ISO-3166 country code for the country where the document is being submitted |
| `countryMandate` | string | The e-invoicing mandate for the specified country |
| `interface` | string | The interface where the document is sent |
| `receiver` | string | The document recipient based on the interface |

### StatusEvent

Displays when a status event occurred

| Property | Type | Description |
|---|---|---|
| `eventDateTime` | string | The date and time when the status event occured, displayed in the format YYYY-MM-DDThh:mm:ss |
| `message` | string | A message describing the status event |
| `responseKey` | string | The type of number or acknowledgement returned by the tax authority (if applicable). For example, it could be an identification key, acknowledgement code, or any other relevant identifier. |
| `responseValue` | string | The corresponding value associated with the response key. This value is provided by the tax authority in response to the event. |

### SubmitDocument

Allows submission of a document.

| Property | Type | Description |
|---|---|---|
| `metadata` | object | Key value pairs of metadata for a document submission {  "workflowId": "partner-einvoicing", "dataFormat": "ubl-invoice", "dataFormatVersion": "2.1", "countryCode": "SA", "countryMandate": "SA-Phase1-B2B" } |
| `data` | object | The document to be submitted, as indicated by the metadata fields 'dataFormat' and 'dataFormatVersion' |

### ForbiddenError

Returns an optional message with a 'forbidden' response

| Property | Type | Description |
|---|---|---|
| `Message` | string | A message that informs the user that they may not access a resource |

### DocumentSubmissionError

Returns an HTTP status code and message for an 'exception'

| Property | Type | Description |
|---|---|---|
| `StatusCode` | string | The three-digit HTTP status code for the exception |
| `Message` | string | A message explaining the exception |

### BadRequest

Returns an HTTP status code and message for a 'bad request'

| Property | Type | Description |
|---|---|---|
| `error` | string | The three-digit HTTP error code for the bad request |
| `message` | string | A message explaining the bad request |

### NotFoundError

Returns an HTTP error code and message for a 'not found' error

| Property | Type | Description |
|---|---|---|
| `error` | string | The three-digit HTTP error code for a not found error |
| `message` | string | A message about the not found error |

### BadDownloadRequest

Returns an HTTP status code and message for a 'bad request'

| Property | Type | Description |
|---|---|---|
| `error` | string | The three-digit HTTP error code for the bad request |
| `message` | string | A message explaining the bad request |
| `supportedAcceptHeaders` | object | A message explaining the bad request |

### DataInputFieldsResponse

Response model providing a list of input fields required, optional, or conditional for different country mandates.

| Property | Type | Description |
|---|---|---|
| `@recordsetCount` | number | Total count of results |
| `@nextLink` | string |  |
| `value` | array | Array of Data Input Fields |

### DataInputField

The Data Input Field

| Property | Type | Description |
|---|---|---|
| `id` | string | Field UUID |
| `fieldId` | string | Field ID |
| `applicableDocumentRoots` | array |  |
| `path` | string | Path to this field |
| `namespace` | string | Namespace of this field |
| `fieldName` | string | Field name |
| `exampleOrFixedValue` | string | An example of the content for this field |
| `acceptedValues` | object | An object representing the acceptable values for this field |
| `documentationLink` | string | An example of the content for this field |
| `description` | string | A description of this field |
| `isSegment` | boolean | Is this a segment of the schema |
| `requiredFor` | object | Array of CountryMandate names for which this field is required. |
| `conditionalFor` | array |  |
| `notUsedFor` | object | Array of CountryMandate names for which this field is not used. |
| `optionalFor` | object | Array of CountryMandate names for which this field is optional. |

### ApplicableDocumentRootsField

Document types for which this field is applicable for

### ConditionalForField

Mandates for which this field is conditional

| Property | Type | Description |
|---|---|---|
| `countryMandate` | string |  |
| `requiredWhen` | array | Array of scenarios which describe when a particular field is conditional for a country mandate |

### RequiredWhenField

Mandates for which this field is required

| Property | Type | Description |
|---|---|---|
| `scenario` | string |  |

### OptionalForField

Mandates for which this field is optional

### NotUsedForField

Mandates for which this field is not used

| Property | Type | Description |
|---|---|---|
| `countryMandate` | string |  |

### MandateDataInputFieldsResponse

Array of Data Input Fields

### MandateDataInputField

The Data Input Field

| Property | Type | Description |
|---|---|---|
| `fieldId` | string | Field ID |
| `documentType` | string | The document type |
| `documentVersion` | string | The document version |
| `path` | string | Path to this field |
| `pathType` | string | The type of path |
| `fieldName` | string | Field name |
| `namespace` | object | The namespace of the UBL element |
| `exampleOrFixedValue` | string | An example of the content for this field |
| `acceptedValues` | array | An Array representing the acceptable values for this field |
| `documentationLink` | string | An example of the content for this field |
| `dataType` | string | The data type of this field. |
| `description` | string | A description of this field |
| `optionality` | string | Determines if the field if Required/Conditional/Optional or not required. |
| `cardinality` | string | Represents the number of times an element can appear within the document |

### InternalServerError

Returns an optional message with a 'InternalServerError' response

| Property | Type | Description |
|---|---|---|
| `error` | string | A bad request error code |
| `message` | string | A message explaining the bad request error |

### MandatesResponse

Mandate list response schema

| Property | Type | Description |
|---|---|---|
| `@recordsetCount` | number | Total count of results |
| `@nextLink` | string |  |
| `value` | array | Mandates schema |

### Mandate

An object representing the country mandate

| Property | Type | Description |
|---|---|---|
| `mandateId` | string | The `mandateId` is comprised of the country code, mandate type, and the network or regulation type (for example, AU-B2G-PEPPOL). Keep in mind the following when specifying a `mandateId`.
- A country can have multiple mandate types (B2C, B2B, B2G).
- A entity/company can opt in for multiple mandates.
- A `mandateId` is the combination of country + mandate type + network/regulation. |
| `countryMandate` | string | **[LEGACY]** This field is retained for backward compatibility. It is recommended to use `mandateId` instead.
The `countryMandate` similar to the `mandateId` is comprised of the country code, mandate type, and the network or regulation type (for example, AU-B2G-PEPPOL). |
| `countryCode` | string | Country code |
| `description` | string | Mandate description |
| `supportedByELRAPI` | boolean | Indicates whether this mandate supported by the ELR API |
| `mandateFormat` | string | Mandate format |
| `eInvoicingFlow` | string | The type of e-invoicing flow for this mandate |
| `eInvoicingFlowDocumentationLink` | string | Link to the documentation for this mandate's e-invoicing flow |
| `getInvoiceAvailableMediaType` | array | List of available media types for downloading invoices for this mandate |
| `supportsInboundDigitalDocument` | string | Indicates whether this mandate supports inbound digital documents |
| `inputDataFormats` | array | Format and version used when inputting the data |
| `workflowIds` | array | Workflow ID list |

### inputDataFormats

Format and version used when inputting the data

| Property | Type | Description |
|---|---|---|
| `format` | string | Document format |
| `versions` | array |  |

### InputDataFormatVersions

Document format version

### WorkflowIds

Workflow ID list

| Property | Type | Description |
|---|---|---|
| `name` | string | The name of this workflow |
| `description` | string | Workflow description |