Attention!

Looking for the most up-to-date Sales Tax Filing or CertManager documentation? Go to our new documentation platform, Sovos Docs. For Global Tax Determination, connector and CertManager API docs, stay here.

Pull exemption metadata

Single exemption

Use this request to pull the metadata for a single exemption in CertManager. You will need the unique exemption ID received in the response when creating the exemption.

Request information

  • HTTP method: GET
  • URL (Replace exemptionId with the ID of the exemption you want to pull)
    • CertManager UAT: https://certmanager-uat.sovos.com/api/pre-auth/v1/certificates/public/exemptions/exemptionId
    • CertManager Production: https://certmanager.sovos.com/api/pre-auth/v1/certificates/public/exemptions/exemptionId

Parameters

Field

Field type

Data type

Required or optional

Description
exemptionId Path String Required The exemption ID
customerId Query Integer Optional

The ID of the customer associated with the exemption

If you pass this field, the request will only return an exemption that matches both the exemptionId and customerId
showVersions Query Boolean Optional

If true, all versions of the exemption will be returned in the response

If false, only the current version of the exemption will be returned in the response

Example response

{
     "status": 200,
     "message": "CorrelationId: 1636133311776 - Exemption Id: bf081f84-35d4-4c5e-8d19-80dec9272010 ShowVersions: true",
     "data": {
          "currentExemption": {
               "id": "bf081f84-35d4-4c5e-8d19-80dec9272010",
               "creationDate": 1635969861058,
               "certificateNumber": "10101",
               "continuous": false,
               "creationBy": "Public API",
               "effectiveDate": 1669852800000,
               "entityUseCode": {
                    "entityUseCode": 113,
                    "entityUseName": "RESA - Resale Certificate",
                    "description": "Resale"
               },
               "exemptionCustomers": [
                    {
                         "id": "446158c5-bb72-467a-b62c-97608736ac5e",
                         "customerId": "ac66955a-31f5-4f92-93d3-f21f73c0832c",
                         "customerName": "City of Boston",
                         "gtdErrorMessage": null,
                         "synced": false
                    }
               ],
               "exemptionStatus": "INITIAL",
               "expirationDate": 1702166400000,
               "gtdSyncStatus": "NOT_IN_GTD",
               "image": {
                    "id": "eee9761d-371c-4644-8068-ab83e3f34a39",
                    "fileName": "file.pdf",
                    "dateOfUpload": 1635969861059,
                    "pageCount": 1,
                    "priority": false,
                    "receivedFrom": "Public API",
                    "orgId": "5d4695bd-fa52-4e29-b289-6040c03c329f",
                    "jwtId": null,
                    "exemptionId": null
               },
               "incompleteReasons": [],
               "inherited": false,
               "jurisdiction": {
                    "jurisdictionId": 262,
                    "name": "NEW YORK",
                    "isoCode": "NY",
                    "type": 2,
                    "parentJurisdictionId": 227
               },
               "notes": null,
               "oldEffectiveDate": null,
               "orgId": "5d4695bd-fa52-4e29-b289-6040c03c329f",
               "skus": [],
               "state": {
                    "stateCode": "NY",
                    "stateName": "NEW YORK",
                    "countryCode": "US",
                    "jurisdictionId": 262,
               },
               "submissionType": "PUBLIC_API",
               "sunsetBy": null,
               "sunsetDate": null
          },
          "historicalExemption": []
     },
     "success": true
}

Multiple exemptions

Use this request to retrieve the metadata for a list of exemptions in CertManager. You can retrieve a list of all exemptions or filter the list of exemptions.

Request information

  • HTTP method: GET
  • URL
    • CertManager UAT: https://certmanager-uat.sovos.com/api/pre-auth/v1/certificates/public/exemptions
    • CertManager Production: https://certmanager.sovos.com/api/pre-auth/v1/certificates/public/exemptions

Parameters

Field

Field type

Data type

Required or optional

Description
page Query Numeric Optional

The page of exemptions to return. This field will apply after the sortBy, order, and perPage fields are applied.

0 is the first page.
perPage Query Numeric Optional The number of exemptions to return per page
order Query String Optional

If ASC, the exemption list will be sorted by the sortBy value in ascending order

If DES, the exemption list will be sorted by the sortBy value in descending order
sortBy Query String Optional The field in this table that you want to sort the exemption list by
customerId Query Numeric Optional The ID of the customer associated with the exemption
state Query String Optional The exemption's state or province
lastModifiedBy Query String Optional The user who last modified the exemption
lastModifiedDate Query String Optional Filter by lastModifiedDate to return all exemptions last modified on, before, or after that date, depending on the value of lastModifiedDateIs
lastModifiedEndDate Query String Optional Filter by lastModifiedDate and lastModifiedEndDate to return all exemptions last modified in that date range
lastModifiedDateIs Query String Optional

Determines how the list is filtered by the last modified date

Possible values:

  • is (default)
  • before
  • after
  • between
certificateNumber Query String Optional The exemption's certificate number
effectiveDate Query String Optional Filter by effectiveDate to return all exemptions effective on, before, or after that date, depending on the value of effectiveDateIs
effectiveEndDate Query String Optional Filter by effectiveDate and effectiveEndDate to return all exemptions effective in that date range
effectiveDateIs Query String Optional

Determines how the list is filtered by the effective date

Possible values:

  • is (default)
  • before
  • after
  • between
expirationDate Query String Optional Filter by expirationDate to return all exemptions that will be expired before, on, or after that day, depending on the value of expirationDateIs
expirationEndDate Query String Optional Filter by expirationDate and expirationEndDate to return all exemptions that will expire in that date range
expirationDateIs Query String Optional

Determines how the list is filtered by the expiration date

Possible values:

  • is (default)
  • before
  • after
  • between
incompleteReason Query Numeric Optional

The exemption's reason for incomplete code

To filter by multiple codes, enter the codes in a comma-separated list
incompleteReasonDescription Query String Optional

The description of the exemption's reason for incomplete code
entityUseCode Query Numeric Optional

The exemption's Entity/Use Code

To filter by multiple codes, enter the codes in a comma-separated list
entityUseCodeDescription Query String Optional

The description of the exemption's Entity/Use Code
exemptionStatus Query String Optional

The status of the exemption in the workflow

Possible values:

  • INITIAL
  • IN_PROGRESS
  • AUDITABLE_COMPLETE
  • AUDITABLE_INCOMPLETE
incomplete Query Boolean Optional

If true, the list will only include incomplete exemptions

If false, the list will only include complete exemptions
expired Query Boolean Optional If true, the list will only include expired exemptions

If false, the list will only include exemptions that have not expired
gtdSyncStatus Query String Optional

The GTD sync status of the exemption

Possible values:

  • SYNCED
  • NOT_IN_GTD
  • OUT_OF_SYNC
  • PENDING
exemptionActiveStatus Query String Optional

The status of the exemption based on the effective and expiration dates

Possible values:

  • ACTIVE
  • EXPIRED
  • PENDING
  • UNKOWN
submissionType Query String Optional

The original method of submission of the exemption

Possible values:

  • UI
  • PUBLIC_API
  • WIZARD
isInherited Query Boolean Optional If true, the list will only include inherited exemptions

If false, the list will only include non-inherited exemptions
notes Query String Optional Notes about the exemption
skus Query String Optional The exemption's list of SKUs
skuType Query String Optional

Possible values:

  • Include
  • Exclude
filename Query String Optional The file name of the exemption certificate
dateOfUpload Query String Optional The date the exemption was uploaded
dateOfUploadIs Query String Optional The user who uploaded the exemption
customerNameOrNumber Query String Optional The name or number of the exemption's customer

Example response

{
     "status": 200,
     "message": "CorrelationId: 10090f76-f760-4a5a-8f71-4bf23024533c - Retrieved Exemptions",
     "data": {
          "pageState": {
               "page": 0,
               "perPage": 50,
               "totalPages": 1,
               "totalEntries": 2
          },
          "items": {
               "content": [
                    {
                         "id": "08c1d101-7313-439e-9f88-d48485d8a985",
                         "creationDate": 1733521148066,
                         "creationBy": "Public API",
                         "certificateNumber": "1",
                         "notes": null,
                         "effectiveDate": 1711929600000,
                         "expirationDate": 1725148800000,
                         "inherited": false,
                         "submissionType": "PUBLIC_API",
                         "gtdSyncStatus": "SYNCED",
                         "exemptionStatus": "AUDITABLE_COMPLETE",
                         "activeStatus": "EXPIRED",
                         "stateProvinceCode": "TX",
                         "reasonForExemption": "Agriculture",
                         "jurisdiction": {
                              "jurisdictionId": 251,
                              "name": "TEXAS",
                              "isoCode": "TX",
                              "type": 2,
                              "parentJurisdictionId": 227
                         },
                         "applyToSubJurisdictions": true,
                         "customerId": "182586f3-9bdb-4fbb-970c-e26c10514287",
                         "customerName": "name",
                         "customerNumber": "number",
                         "gtdErrorMessage": null,
                         "imageId": "ba9dc522-63d9-4987-8974-ab74ac362453",
                         "fileName": "city_5.pdf",
                         "dateOfUpload": 1733521148068,
                         "reasonsForIncomplete": ""
                    },
                    {
                         "id": "b16e7f76-d09d-430c-86be-db2f9aacfe95",
                         "creationDate": 1733520706835,
                         "creationBy": "Public API",
                         "certificateNumber": "123",
                         "notes": null,
                         "effectiveDate": 0,
                         "expirationDate": null,
                         "inherited": false,
                         "submissionType": "PUBLIC_API",
                         "gtdSyncStatus": "SYNCED",
                         "exemptionStatus": "AUDITABLE_COMPLETE",
                         "activeStatus": "ACTIVE",
                         "stateProvinceCode": "NM",
                         "reasonForExemption": "Non-profit activity",
                         "jurisdiction": {
                              "jurisdictionId": 263,
                              "name": "NEW MEXICO",
                              "isoCode": "NM",
                              "type": 2,
                              "parentJurisdictionId": 227
                         },
                         "applyToSubJurisdictions": true,
                         "customerId": "824512ea-8e62-428f-9f5a-faa4b48bc2e6",
                         "customerName": "name2",
                         "customerNumber": "number2",
                         "gtdErrorMessage": null,
                         "imageId": "d95c54ab-fa5e-45c6-a4f4-2cb6060b2ab9",
                         "fileName": "TestCertificate.pdf",
                         "dateOfUpload": 1733520706835,
                         "reasonsForIncomplete": ""
                    }
               ],
               "pageable": {
                    "pageNumber": 0,
                    "pageSize": 50,
                    "sort": {
                         "unsorted": false,
                         "sorted": true,
                         "empty": false
                    },
                    "offset": 0,
                    "unpaged": false,
                    "paged": true
               },
               "totalElements": 8924,
               "totalPages": 179,
               "last": false,
               "first": true,
               "numberOfElements": 50,
               "size": 50,
               "number": 0,
               "sort": {
                    "unsorted": false,
                    "sorted": true,
                    "empty": false
               },
               "empty": false
          }
     },
     "success": true
}