Release Notes Downloads FAQs

Get Account Info

GET /v9/account

Retrieve your account's current information.

Notes

Request Headers

Header Data Type Required Description
Sovren-AccountId string Yes The Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKey string Yes The Service key that is provided to you for access to your account’s available credits.
Content-Type string Yes Indicates the media type of the incoming request body. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": {
        "CreditsRemaining": 0,
        "CreditsUsed": 0,
        "MaximumConcurrentRequests": 0,
        "ExpirationDate": ""
    }
}
Field Data Type Description
Info.Code string A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided
Info.Message string This message further describes the code providing additional detail.
Value.CreditsUsed decimal The total number of credits that have been executed for the account.
Value.CreditsRemaining decimal The total number of credits remaining for the account.
Value.ExpirationDate string The expiration date for the account.
Value.MaximumConcurrentRequests integer The maximum amount of bulk concurrent requests that your account is allowed to submit to the web service. This doesn't pertain to parsing transactions initiated by an end user ("Ad Hoc Transaction"), but is intended to limit concurrent transactions when a batch of documents need to be parsed in a background process that is controlled by developers ("Batch Transaction"). If you need to process a batch with more concurrent requests reach out to sales@sovren.com. More details can be found in Sovren's Acceptable Use Policy.

Create a Skills List

POST /v9/skills

Upload a custom data list to be optionally used during parsing.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • For custom skills implementation, we recommend using the Sovren Skills Editor utility, which provides a rich GUI for skills management. You can download the utility from My Sovren Portal.

Request Headers

Header Data Type Required Description
Sovren-AccountId string Yes The Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKey string Yes The Service key that is provided to you for access to your account’s available credits.
Content-Type string Yes Indicates the media type of the incoming request body. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Request Body

{
  "Name": "",
  "Culture": "",
  "Content": [
    ""
  ]
}
Field Data Type Required Description
Name string Yes A name for the data being uploaded. Names must consist of only letters, digits, and ASCII hyphens. If the combination of Name and Culture already exists, it is overwritten.
Culture string Yes The culture or language of the data, formatted as an ISO 639-1 two letter language code. Click here for a list of supported languages currently supported by the parser.
Content string[] Yes The Content of data being uploaded. Pass Taxonomy SDF in the first array element and Skills SDF in the second array element. To generate SDF content, see the specifications in the Customizing Skills document. To upload Content as binary data, Base64 encode the data and add the “text/base64:” prefix.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": {
        "Key": "",
        "Name": ""
    }
}
Field Data Type Description
Info.Code string A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided
Info.Message string This message further describes the code providing additional detail.
Value.Key string The unique Key for the data list.
Value.Name string The Name of the data list.

Update a Skills List

PUT /v9/skills/{key}

Update a specified list to be optionally used during parsing.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • For custom skills implementation, we recommend using the Sovren Skills Editor utility, which provides a rich GUI for skills management. You can download the utility from My Sovren Portal.

Request Headers

Header Data Type Required Description
Sovren-AccountId string Yes The Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKey string Yes The Service key that is provided to you for access to your account’s available credits.
Content-Type string Yes Indicates the media type of the incoming request body. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Path Parameters

Parameter Data Type Description
key string The key for the skill data list to update.

Request Body

{
  "Content": [
    ""
  ]
}
Field Data Type Required Description
Content string[] Yes The Content of data being uploaded. Pass Taxonomy SDF in the first array element and Skills SDF in the second array element. To generate SDF content, see the specifications in the Customizing Skills document. To upload Content as binary data, Base64 encode the data and add the “text/base64:” prefix.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": {
        "Key": "",
        "Name": ""
    }
}
Field Data Type Description
Info.Code string A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided

DataNotFound - Data with the specified name wasn't found
Info.Message string This message further describes the code providing additional detail.
Value.Key string The unique Key for the updated data list.
Value.Name string The Name of the updated data list

Get a Skills List

GET /v9/skills/{key}

Retrieve the data from a specified list to be optionally used during parsing.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • For custom skills implementation, we recommend using the Sovren Skills Editor utility, which provides a rich GUI for skills management. You can download the utility from My Sovren Portal.

Request Headers

Header Data Type Required Description
Sovren-AccountId string Yes The Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKey string Yes The Service key that is provided to you for access to your account’s available credits.
Content-Type string Yes Indicates the media type of the incoming request body. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Path Parameters

Parameter Data Type Description
key string The key for the skill data list to retrieve.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": [
        ""
    ]
}
Field Data Type Description
Info.Code string A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided

DataNotFound - Data with the specified name wasn't found
Info.Message string This message further describes the code providing additional detail.
Value string[] The Content of data in string array form. For custom skills, the first element (Value[0]) contains the Taxonomies text while the second element (Value[1]) the Skills text. The skills and taxonomies can be returned in either plain text or binary data. The binary data will be Base64 encoded and will contain a "text/base64:" prefix.

List All Skills Lists

GET /v9/skills

Retrieve your account's current custom skills data lists.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • For custom skills implementation, we recommend using the Sovren Skills Editor utility, which provides a rich GUI for skills management. You can download the utility from My Sovren Portal.

Request Headers

Header Data Type Required Description
Sovren-AccountId string Yes The Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKey string Yes The Service key that is provided to you for access to your account’s available credits.
Content-Type string Yes Indicates the media type of the incoming request body. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": [
        {
            "Key": "",
            "Name": ""
        }
    ]
}
Field Data Type Description
Info.Code string A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided

DataNotFound - Data with the specified name wasn't found
Info.Message string This message further describes the code providing additional detail.
Value[i].Key string The unique Key for the data list.
Value[i].Name string The Name of the data list

Delete a Skills List

DELETE /v9/skills/{key}

Delete a specified list to be optionally used during parsing.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • For custom skills implementation, we recommend using the Sovren Skills Editor utility, which provides a rich GUI for skills management. You can download the utility from My Sovren Portal.

Request Headers

Header Data Type Required Description
Sovren-AccountId string Yes The Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKey string Yes The Service key that is provided to you for access to your account’s available credits.
Content-Type string Yes Indicates the media type of the incoming request body. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Path Parameters

Parameter Data Type Description
key string The key for the skill data list to delete.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": { }
}
Field Data Type Description
Info.Code string A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided

DataNotFound - Data with the specified name wasn't found
Info.Message string This message further describes the code providing additional detail.
Value object An empty object.

Create a Normalizations List

POST /v9/normalizations

Upload a custom data list to be optionally used during parsing.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • For custom normalization implementation, we recommend using the Sovren Normalization Editor utility, which provides a rich GUI for normalization management. You can download the utility from My Sovren Portal.

Request Headers

Header Data Type Required Description
Sovren-AccountId string Yes The Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKey string Yes The Service key that is provided to you for access to your account’s available credits.
Content-Type string Yes Indicates the media type of the incoming request body. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Request Body

{
  "Name": "",
  "Culture": "",
  "ContentBytes": ""
}
Field Data Type Required Description
Name string Yes A name for the data being uploaded. Names must consist of only letters, digits, and ASCII hyphens. If the combination of Name and Culture already exists, it is overwritten.
Culture string Yes The culture or language of the data, formatted as an ISO 639-1 two letter language code. Click here for a list of supported languages currently supported by the parser.
ContentBytes string Yes The byte content of the normalization lists in .zip file format. Archive the normalization lists into a .zip file and pass them within this field as a Base64-encoded string of bytes.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": {
        "Key": "",
        "Name": ""
    }
}
Field Data Type Description
Info.Code string A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided
Info.Message string This message further describes the code providing additional detail.
Value.Key string The unique Key for the data list.
Value.Name string The Name of the data list.

Update a Normalizations List

PUT /v9/normalizations/{key}

Update a specified list to be optionally used during parsing.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • For custom normalization implementation, we recommend using the Sovren Normalization Editor utility, which provides a rich GUI for normalization management. You can download the utility from My Sovren Portal.

Request Headers

Header Data Type Required Description
Sovren-AccountId string Yes The Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKey string Yes The Service key that is provided to you for access to your account’s available credits.
Content-Type string Yes Indicates the media type of the incoming request body. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Path Parameters

Parameter Data Type Description
key string The key for the normalization data list to update.

Request Body

{
  "ContentBytes": ""
}
Field Data Type Required Description
ContentBytes string Yes The byte content of the normalization lists in .zip file format. Archive the normalization lists into a .zip file and pass them within this field as a Base64-encoded string of bytes.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": {
        "Key": "",
        "Name": ""
    }
}
Field Data Type Description
Info.Code string A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided

DataNotFound - Data with the specified name wasn't found
Info.Message string This message further describes the code providing additional detail.
Value.Key string The unique Key for the updated data list.
Value.Name string The Name of the updated data list

Get a Normalizations List

GET /v9/normalizations/{key}

Retrieve the data from a specified list to be optionally used during parsing.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • For custom normalization implementation, we recommend using the Sovren Normalization Editor utility, which provides a rich GUI for normalization management. You can download the utility from My Sovren Portal.

Request Headers

Header Data Type Required Description
Sovren-AccountId string Yes The Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKey string Yes The Service key that is provided to you for access to your account’s available credits.
Content-Type string Yes Indicates the media type of the incoming request body. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Path Parameters

Parameter Data Type Description
key string The key for the normalization data list to retrieve.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": ""
}
Field Data Type Description
Info.Code string A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided

DataNotFound - Data with the specified name wasn't found
Info.Message string This message further describes the code providing additional detail.
Value string A Base64-encoded string of bytes representing the zip file containing normalization data.

Get All Normalizations Lists

GET /v9/normalizations/

Retrieve your account's current custom normalization data.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • For custom normalization implementation, we recommend using the Sovren Normalization Editor utility, which provides a rich GUI for normalization management. You can download the utility from My Sovren Portal.

Request Headers

Header Data Type Required Description
Sovren-AccountId string Yes The Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKey string Yes The Service key that is provided to you for access to your account’s available credits.
Content-Type string Yes Indicates the media type of the incoming request body. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": [
        {
            "Key": "",
            "Name": ""
        }
    ]
}
Field Data Type Description
Info.Code string A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided

DataNotFound - Data with the specified name wasn't found
Info.Message string This message further describes the code providing additional detail.
Value[i].Key string The unique Key for the data list.
Value[i].Name string The Name of the data list

Delete a Normalizations List

DELETE /v9/normalizations/{key}

Delete a specified list to be optionally used during parsing.

Notes

  • You can try this endpoint out at our Swagger page ( US Data Center | EU Data Center )
  • For custom normalization implementation, we recommend using the Sovren Normalization Editor utility, which provides a rich GUI for normalization management. You can download the utility from My Sovren Portal.

Request Headers

Header Data Type Required Description
Sovren-AccountId string Yes The Account ID that is provided to you when establishing your Service Account.
Sovren-ServiceKey string Yes The Service key that is provided to you for access to your account’s available credits.
Content-Type string Yes Indicates the media type of the incoming request body. Supported values are application/json and application/xml.
Accept string No Controls the media type of the response body. Supported values are application/json and application/xml. If not specified the response will default to JSON.

Path Parameters

Parameter Data Type Description
key string The key for the normalization data list to delete.

Response Body

{
    "Info": {
        "Code": "",
        "Message": ""
    },
    "Value": { }
}
Field Data Type Description
Info.Code string A response code elaborating on the HTTP status code.
The following is a list of codes that can be returned by the service:

Success – Successful transaction

MissingParameter - A required parameter wasn't provided

InvalidParameter - A parameter was incorrectly specified

AuthenticationError - An error occurred with the credentials provided

DataNotFound - Data with the specified name wasn't found
Info.Message string This message further describes the code providing additional detail.
Value object An empty object.