# Shared Company Service API

APIs for managing canonical Company and Contact information across Avalara products.

This API is hosted under https://api.avalara.com.

Version 1.2 introduces support for company identifiers: 
- urn:avalara:company:identifier:global:gs1:gln (Global Location Number)
- urn:avalara:company:identifier:global:dnb:duns (DUNS)
- urn:avalara:company:identifier:global:gleif:lei (Legal Entity Identifier)

Source: https://developer.avalara.com/products/shared-services/api/

**Version:** 1.2
**Base URL:** https://api.avalara.com/scs

---

## Endpoints

### Companies

#### Retrieve all companies

`GET /companies`

Use this endpoint to retrieve all companies for a calling tenant. Company identifiers are only returned when included in the $include parameter.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `$include` | string | query | No | A comma separated list of objects to fetch underneath this company. Any object with a URL path underneath this company can be fetched by specifying its name. Use 'companyIdentifiers' to include company identifiers in the response. |
| `$filter` | string | query | No | A filter statement to identify specific records to retrieve. |
| `$top` | integer | 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` | integer | query | No | If nonzero, skip this number of results before returning data. Used with `$top` to provide pagination for large datasets. |
| `$orderBy` | string | query | No | A comma separated list of ascending or descending sort statements in the format `(fieldname) [ASC|DESC]`, for example `companyCode DESC` |
| `returnHierarchy` | boolean | query | No | `false` by default. If `true`, then the API will return the entire hierarchy of the company specified in the filter. |
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |

#### Create a company

`POST /companies`

Use this endpoint to create a company. Company identifiers support is available in version 1.2+.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |

#### Retrieve a single company

`GET /companies/{companyId}`

Use this endpoint to retrieve information about a single company. Company identifiers are returned if they exist for the company, regardless of API version.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |

#### Update a single company

`PUT /companies/{companyId}`

Use this endpoint replace the existing company object at this URL with an updated object. Company identifiers support is available in version 1.2+.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |

#### Delete a single company

`DELETE /companies/{companyId}`

Use this endpoint to delete a company.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |


### Contacts

#### Retrieve all contacts for a company

`GET /companies/{companyId}/contacts`

Use this endpoint to retrieve all contacts for a specific `companyId`.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `companyId` | string | path | Yes | The ID of the company. Run `get /companies` for a list of available company IDs. |
| `$include` | string | query | No | A comma separated list of objects to fetch underneath this company. Any object with a URL path underneath this company can be fetched by specifying its name.

For more information on filtering, see [Filtering in REST](https://developer.avalara.com/avatax/filtering-in-rest/). |
| `$filter` | string | query | No | A filter statement to identify specific records to retrieve.

For more information on filtering, see [Filtering in REST](https://developer.avalara.com/avatax/filtering-in-rest/). |
| `$top` | integer | 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` | integer | query | No | If nonzero, skip this number of results before returning data. Used with `$top` to provide pagination for large datasets. |
| `$orderBy` | string | query | No | A comma separated list of ascending or descending sort statements in the format `(fieldname) [ASC|DESC]`, for example `contactCode DESC` |
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |

#### Create contacts

`POST /companies/{companyId}/contacts`

Use this endpoint to create contacts for a specific `companyId`.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `companyId` | string | path | Yes | The ID of the company. Run `get /companies` for a list of available company IDs. |
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |

#### Retrieve a single contact for a specific company

`GET /companies/{companyId}/contacts/{contactId}`

Use this endpoint to retrieve a specific contact for a specific company.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |

#### Update a single contact

`PUT /companies/{companyId}/contacts/{contactId}`

Use this endpoint replace the existing contact object at this URL with an updated object.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |

#### Delete a single contact

`DELETE /companies/{companyId}/contacts/{contactId}`

Use this endpoint to delete a specific contact.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | API Version |


### Aspects

#### Retrieve all active aspects for a company

`GET /companies/{companyId}/aspects`

Use this endpoint to retrieve all aspects for a specific `companyId`.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `companyId` | string | path | Yes | The ID of the company. Run `get /companies` for a list of available company IDs. |
| `$include` | string | query | No | A comma separated list of objects to fetch underneath this company. Any object with a URL path underneath this company can be fetched by specifying its name.

For more information on filtering, see [Filtering in REST](https://developer.avalara.com/avatax/filtering-in-rest/). |
| `$filter` | string | query | No | A filter statement to identify specific records to retrieve.For more information on filtering, see [Filtering in REST](https://developer.avalara.com/avatax/filtering-in-rest/). 

 *Filterable:* namespace 

 *Operators supported:* EQ/=, IN |
| `$top` | integer | 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` | integer | query | No | If nonzero, skip this number of results before returning data. Used with `$top` to provide pagination for large datasets. |
| `$orderBy` | string | query | No | A comma separated list of ascending or descending sort statements in the format `(fieldname) [ASC|DESC]`, for example `contactCode DESC` |
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |
| `$count` | boolean | query | No | If TRUE, return total count of records falling under the specified criteria from request. |

#### Create aspects for a company

`POST /companies/{companyId}/aspects`

Use this endpoint to create aspects for a specific `companyId`.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `companyId` | string | path | Yes | The ID of the company. Run `get /companies` for a list of available company IDs. |
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |

#### Retrieve a single aspect for a specific company.

`GET /companies/{companyId}/aspects/{aspectKey}`

Use this endpoint to retrieve a specific aspect for a specific company. 

This is the only API which can retrieve even deleted aspect.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |

#### Update a single aspect

`PUT /companies/{companyId}/aspects/{aspectKey}`

Use this endpoint replace the existing aspect object at this URL with an updated object.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | The HTTP Header meant to specify the version of the API intended to be used |

#### Delete a single aspect

`DELETE /companies/{companyId}/aspects/{aspectKey}`

Use this endpoint to delete a specific aspect.

**Parameters:**

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `X-Avalara-Client` | string | header | No | Identifies the software you are using to call this API.  For more information on the client header, see [Client Headers](https://developer.avalara.com/avatax/client-headers/). |
| `X-Correlation-Id` | string | header | No | Use the X-Correlation-ID header to support request correlation through requests. This header should be present on all requests and responses. |
| `avalara-version` | string | header | No | API Version |

---

## Models

### Company

Company model object used to create a company

| Property | Type | Description |
|---|---|---|
| `id` | string | Unique identifier for the given user. |
| `companyName` | string | The company name |
| `defaultCountry` | string | The two character ISO-3166 country code for this company. |
| `tenant` | Reference |  |
| `companyCode` | string | A unique code that references this company within your account |
| `isActive` | boolean | Specifies whether this company is active |
| `hasDirectoryConsent` | boolean | Indicates whether the user has provided consent to include this company in the directory. This field is available starting from API version 1.1. |
| `aspects` | array |  |
| `tags` | array |  |
| `parent` | Reference |  |
| `children` | array | The child companies within this parent company |
| `meta` | Meta |  |
| `ani` | string | Avalara Network Identifier (ANI) - a unique 15-character identifier automatically generated at company creation. |
| `companyIdentifiers` | array | Company identifiers following international standards. |

### CompanyRequest

Object for storing company information

| Property | Type | Description |
|---|---|---|
| `id` | string | Unique identifier for the given user. |
| `companyName` | string | The name of the company |
| `defaultCountry` | string | The two character ISO-3166 country code for this company |
| `tenant` | Reference |  |
| `companyCode` | string | A unique code that references this company within your account |
| `isActive` | boolean | Specifies whether this is an active company |
| `hasDirectoryConsent` | boolean | Indicates whether the user has provided consent to include this company in the directory. This field is available starting from API version 1.1. |
| `aspects` | array |  |
| `tags` | array |  |
| `parent` | CompanyParent |  |
| `companyIdentifiers` | array | Company identifiers following international standards. |

### Aspect

Object for storing one or more aspects for this company (for example, ELR, AvaTax, and so on)

| Property | Type | Description |
|---|---|---|
| `identifier` | string | An Identifier that uniquely identifies belonging aspect for this company in delivery system |
| `displayName` | string | The displayed aspect name |
| `location` | string | The location of this aspect from delivery system |
| `namespace` | string | Namespace uniquely identifies the delivery system |
| `isDeleted` | boolean |  |
| `meta` | Meta |  |

### Info

Response information for requests

| Property | Type | Description |
|---|---|---|
| `title` | string | The title for this response |
| `status` | string | The response status |
| `detail` | string | A detailed response message |
| `instance` | string | Additional information about the response and instance |

### ErrorInfo

Response information for requests that result in an error

| Property | Type | Description |
|---|---|---|
| `title` | string | The title for this error |
| `status` | string | The response status |
| `detail` | string | A detailed error message |
| `instance` | string | Additional information about the error and instance |

### CompanyParent

An object for storing the company identifier

| Property | Type | Description |
|---|---|---|
| `identifier` | string | The ID of the representing entity |

### CompanyContact

Object for storing contact information for a company

| Property | Type | Description |
|---|---|---|
| `id` | string | The ID for this contact |
| `companyId` | string | The company ID for this contact |
| `contactCode` | string | A unique code within the associated company for this contact.
maxLength: 25
minLength: 0 |
| `firstName` | string | The first or given name of this contact.
maxLength: 50
minLength: 0 |
| `middleName` | string | The middle name of this contact.
maxLength: 50
minLength: 0 |
| `lastName` | string | The last or family name of this contact.
maxLength: 50
minLength: 0 |
| `title` | string | Professional title of this contact.
maxLength: 50
minLength: 0 |
| `line1` | string | The first line of the postal mailing address of this contact.
maxLength: 100
minLength: 0 |
| `line2` | string | The second line of the postal mailing address of this contact.
maxLength: 50
minLength: 0 |
| `line3` | string | The third line of the postal mailing address of this contact.
maxLength: 50
minLength: 0 |
| `city` | string | The city of the postal mailing address of this contact.
maxLength: 50
minLength: 0 |
| `region` | string | Name or ISO 3166 code identifying the region within the country. |
| `postalCode` | string | The postal code or zip code of the postal mailing address of this contact.
maxLength: 10
minLength: 0 |
| `country` | string | This field supports many different country identifiers:

Two character ISO 3166 codes
Three character ISO 3166 codes
Fully spelled out names of the country in ISO supported languages
Common alternative spellings for many countries
For a full list of all supported codes and names, please see the Definitions API ListCountries. |
| `email` | string | The email address of this contact. |
| `phone` | string | The main phone number for this contact. |
| `mobile` | string | The mobile phone number for this contact. |
| `fax` | string | The facsimile phone number for this contact. |
| `meta` | Meta |  |

### Tags

Object for creating tags for labeling/organizing companies and contacts

| Property | Type | Description |
|---|---|---|
| `name` | string | The name of the tag |
| `value` | string | The tag value |

### Reference

Object for storing reference information for this entity

| Property | Type | Description |
|---|---|---|
| `identifier` | string | Identifier of the representing entity |
| `displayName` | string | Display name of the representing entity |
| `location` | string | Location of the representing entity in the company URL |

### Meta

Meta data for an entity

| Property | Type | Description |
|---|---|---|
| `createdBy` | string | UUID of the user who created this entity |
| `created` | string | Date/time when the entity was created |
| `modifiedBy` | string | UUID of the user who modified this entity |
| `lastModified` | string | Date/time when the entity was modified |
| `location` | string | The location of this entity in the company URL |
| `version` | string | The entity version |

### CompanyFetchResult

Response returned when querying companies

| Property | Type | Description |
|---|---|---|
| `@recordsetCount` | integer | The number of records in this response |
| `value` | array | The object storing a company record |
| `@nextLink` | string | A link for pagination |
| `pageKey` | string | The page number |

### ContactFetchResult

Response returned when querying contacts

| Property | Type | Description |
|---|---|---|
| `@recordsetCount` | integer | The number of records in this response |
| `value` | array | The object storing a contact record |
| `@nextLink` | string | A link for pagination |
| `pageKey` | string | The page number |

### ResolveCompany

Object for storing company resolution infromation

| Property | Type | Description |
|---|---|---|
| `id` | string | Unique identifier for the given user. |
| `companyName` | string | The company name |
| `companyCode` | string | The company code |
| `isActive` | boolean | Whether this company is active |
| `hasDirectoryConsent` | boolean | Indicates whether the user has provided consent to include this company in the directory. This field is available starting from API version 1.1. |
| `parent` | Reference |  |

### ResolveCompanyRequest

Object for storing company request resolution information

| Property | Type | Description |
|---|---|---|
| `tenantId` | string | The tenant ID for this company |
| `expression` | string | An expression for this request |

### ResolveCompanyFetchResult

Object for storing results when retrieving company information

| Property | Type | Description |
|---|---|---|
| `@recordsetCount` | integer | The number of records in this response |
| `value` | array |  |
| `@nextLink` | string | The page number |

### AspectFetchResult

| Property | Type | Description |
|---|---|---|
| `@recordsetCount` | integer |  |
| `value` | array |  |
| `@nextLink` | string |  |
| `pageKey` | string |  |

### AspectRequest

| Property | Type | Description |
|---|---|---|
| `identifier` | string |  |
| `displayName` | string |  |
| `location` | string |  |
| `namespace` | string |  |

### CompanyIdentifier

Company identifier following international standards

| Property | Type | Description |
|---|---|---|
| `companyServiceId` | string | Unique identifier for the company service |
| `identifierType` | string | The type of company identifier using URN format.

For more information on identifier taxonomy, see [Company Identifier Taxonomies](https://avalara.atlassian.net/wiki/spaces/ATPE/pages/638741779220/Company+Identifier+Taxonomies). |
| `identifierValue` | string | The actual identifier value |
| `created` | string | Date/time when the identifier was created |
| `lastModified` | string | Date/time when the identifier was last modified |
| `createdBy` | string | User who created this identifier |
| `modifiedBy` | string | User who last modified this identifier |

### CompanyIdentifierRequest

Company identifier request object for POST/PUT operations

| Property | Type | Description |
|---|---|---|
| `companyServiceId` | string | Unique identifier for the company service |
| `identifierType` | string | The type of company identifier using URN format.

For more information on identifier taxonomy, see [Company Identifier Taxonomies](https://avalara.atlassian.net/wiki/spaces/ATPE/pages/638741779220/Company+Identifier+Taxonomies). |
| `identifierValue` | string | The actual identifier value |