Overview
|
The Sponsorship API is a not a Public API. As a Partner API, access is restricted to KORE's Customers and their partners. For access to the API please contact your customer success representative to discuss your use-cases. |
The Sponsorship API provides the ability to retrieve entities such as deal sheets, billings, and related items in a secure and easy manner. Our read-only Partner API is a RESTful API that can be used with any client that is able to make HTTP(S) requests and provides an interface that implements our database schema. The API is available for both Standalone and CRM connected deployments of the Sponsorship product.
This document provides the general specification of the API for informational purposes. The end-points that will be available to you will depend on the use-cases that need to be solved in discussion with the KORE team.
The following conventions apply to all API resources and endpoints, except where noted.
Format
Only the JSON format (application/json) is currently supported for this API. This applies to both requests and responses. We may consider supporting other formats in the future if there is a need. The Sponsorship API will always return a well formed JSON response, even in case of an error (see Error Handling for specific details).
We do not use JSON envelopes for responses. When requesting an entity the actual entity object is returned:
{
"created_by_id": "80d62bbf-730b-e811-a95c-000d3a36f6bf",
"created_date": "2018-04-30T16:20:19",
"id": "71a11041-7eb1-422b-8d92-0312f919d79f",
"name": "Regular",
"modified_by_id": "80d62bbf-730b-e811-a95c-000d3a36f6bf",
"modified_date": "2018-04-30T16:20:19",
"state": 0
}
When requesting a collection of entities, a JSON array of entity objects is returned:
{
"id": "71a11041-7eb1-422b-8d92-0312f919d79f",
"created_by_id": "80d62bbf-730b-e811-a95c-000d3a36f6bf",
"created_date": "2018-04-30T16:20:19",
"name": "Regular",
"modified_by_id": "80d62bbf-730b-e811-a95c-000d3a36f6bf",
"modified_date": "2018-04-30T16:20:19",
"state": 0
},
{
"id": "56c1e82c-8292-4463-a678-23819a65ddef",
"created_by_id": "80d62bbf-730b-e811-a95c-000d3a36f6bf",
"created_date": "2018-04-30T16:20:14",
"name": "Post Season",
"modified_by_id": "80d62bbf-730b-e811-a95c-000d3a36f6bf",
"modified_date": "2018-04-30T16:20:14",
"state": 0
}
Versioning
By default, the PSS API URLs point to the latest officially supported version. The API can also provide access to beta versions as a way to give clients early access to new features. This is done by including X-Api-Version header and setting it to the appropriate version. When it's not included the API will use the latest official version.
Error Handling
If there is a problem processing a request, a HTTP response status will be set accordingly. The following error statuses are supported:
| Error Status | |
|---|---|
| 400 | Bad Request (an incorrect request, specific details will be provided in the response) |
| 401 | Authentication Required (authentication header was not provided, or an invalid or expired token was used) |
| 403 | Forbidden (authenticated user does not have authorization to retrieve or update the resource) |
| 404 | Not Found (a non existing entity requested) |
| 500 | Server Error |
In addition to the HTTP response status for some errors (such as 500 Server Errors) additional information will be provided in the response body as a JSON object in the following format:
{
"id": "e3b8f848-bf0c-493a-9398-4408f3b16bee",
"error_id": "a4249274-0488-4ae1-9b7c-1d0be01cca4f",
"error": "Server",
"message": "An error occurred while processing your request. Please contact support and reference the id included in this response.",
"link": null,
"errors": null
}
| Field | Description |
|---|---|
| id | entity item id |
| error_id | A unique reference number for the error. When included please provide it when submitting a ticket to support which will help us to identify and address the issue faster. |
| error | A string representing the error category. Possible values are:
|
| message | A detailed error message |
| link | Reserved for future use |
| errors | A collection of additional error messages in case when there are multiple errors (mainly applies to Validation error category). |
Authentication
All requests must be made using secure connections (https). Unsecured connections to the API will be rejected. Each request must include 2 headers:
| X-Api-Key | The value to use will be provided by KORE |
|---|---|
| Authorization | The authorization header |
The Sponsorship API uses a bearer token OAUTH flow. Authorization header must be in the following format, where TOKEN is the token string:
Bearer tokens can be obtained by making a POST request to the following endpoint:
https://koreauth.koresoftware.com/connect/token
You can specify client_id and client_secret in the body instead of using Authorization header. If you use this method you will need to URL encode the client secret:
If a request is made successfully a valid token will be returned as a JSON object:
Alternatively, you can specify Authorization header using Basic auth:
CREDENTIALS is client_id:client_secret string converted to Base64 format. KORE will provide you with the client_id and the client_secret to use (for convenience we can also provide CREDENTIALS value already converted to Base64).
The body of the request should specify the grant type and the optionally scope. If scope is not provided all scopes are granted (and generally limited to pss-api for most users to begin with):
Example in Postman
An example of a call to obtain a bearer token:
POST /connect/token HTTP/1.1
Host: koreauth.koresoftware.com
Content-Type: application/x-www-form-urlencoded
Authorization: None
Cache-Control: no-cache
grant_type=client_credentials&client_id=[CLIENTID]&client_secret=[SECRET]
Example Response:
{
"access_token": "eyh5sbGciOiJSUzI1NiIsIm23423dnj3jid....",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "pss-api"
}
Once you have the access token, you can then call the Sponsorship API with an Authorization header set to "Bearer", with the value obtained from "access_token" response.
Example Call to Sponsorship API (get all users):
GET /users/current HTTP/1.1
Host: api.koresoftware.com
Content-Type: application/json
Authorization: [ACCESS TOKEN FROM ABOVE CALL]
X-Api-Key: [KEY PROVIDED BY KORE]
X-Api-Version: 1
Cache-Control: no-cache
Cross-Origin Resource Sharing (CORS)
The Sponsorship API supports Cross-Origin Resource Sharing (CORS). When a valid request is made to the API and it includes Origin header, the API will include Access-Control-Allow-Origin header in its response, set to * (wildcard). The API will also respond to pre-flight requests (OPTIONS requests) by returning a response with the following headers:
| Access-Control-Allow-Headers | Connection,Cache-Control,Expires,Pragma,Authorization,X-Api-Key,Content-Type,Content-Length |
| Access-Control-Allow-Methods | GET,HEAD,OPTIONS |
| Access-Control-Allow-Origin | * |
| Access-Control-Max-Age | 1800 |
Getting Started
The Sponsorship API is a RESTful API and as such follows typical RESTful conventions. Requests can be made to obtain various resources using standard HTTP verbs (where a resource is one of the Sponsorship entities). Requests must be made using JSON format, and responses will be represented in JSON as well.
Before any requests can be made you will need to obtain an authorization token. The API requires a valid bearer token to be provided with each request. To obtain a token you will need to do the following:
- Get your client_id and client_secret from Kore
- Make a POST request to https://koreauth.koresoftware.com/connect/token with the request body set to:
grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret
If the request was successfully processed you should get a JSON object back which will contain access_token field. The value of this field is your bearer token.
Now that you have a bearer token you can try and obtain a resource. Let's get a list of billings:
- Make a GET request to https://api.koresoftware.com/entities/billings
using the following headers (BEARERTOKEN is the bearer token, and APIKEY should be provided to you by Kore):
Authorization: Bearer BEARERTOKEN
X-Api-Key: APIKEY
Assuming you have access to billings records you should get an array of billings back. This collection is paged - it will only return a 100 or less records at a time. You can use query parameters to select which page to get. The 2 parameters you would use for this are skip (which specifies how many records to skip) and top (which specifies how many records to return).
Assuming a page contains 100 items you can retrieve the first page by making a GET request with the following parameters:
https://api.koresoftware.com/entities/billings?skip=100&top=100
If you just need to get one billing, and you already know the billing id you can simply use the following URL (replace {id} with the billing id):
https://api.koresoftware.com/entities/billings/{id}
We recommend using User-Agent header and setting it to the name of your organization - this will help us to identify and fix any possible issues faster.
Supported Operations
The API currently supports read-only Use Cases (GET):
- To get an item make a GET request to /entities/entity/id
- To get multiple items make a GET request to /entities/entity
Date Formats
The API uses the following conventions when dealing with dates:
- All dates are formatted according to ISO 8601, extended format (for example: 2018-11-25, 2018-11-25T13:12:59, 2018-11-25T13:12:59Z, 2018-11-25T13:12:59+08:00)
- Currently only extended format is supported (with "-" included). We may consider adding support for basic ISO 8601 in the future if there is a need.
- Milliseconds are accepted but will be ignored
The API supports 3 different formats for dates and/or timestamps:
Date
Used for fields that do not include timestamps
Requests / queries: timestamp and timezone information is ignored, no timezone conversion is done. Dates are stored as provided.
Responses: only date is returned (yyyy-MM-dd)
DateTime
Used for fields set by users (dates are expected to be stored and returned exactly as provided with no timezone conversion
Requests / queries: timezone information is ignored, no timezone conversion is done. Dates and times are stored and returned as provided.
Responses: only date and time is returned, no timezone (yyyy-MM-ddTHH:mm:ss)
SystemDateTime
Used for system dates, such as created_date and modified_date
Requests / queries: system dates are not updateable via requests. For queries any extended ISO 8601 format is accepted, time will be converted to UTC according to the timezone provided. If no timezone information is provided UTC will be assumed.
Responses: both date and time are returned with UTC timezone specified (yyyy-MM-ddTHH:mm:ssZ)
Queries
It is possible to search, filter, sort and page results when performing a GET. This is done by using query parameters. The following parameters are supported for bulk GET (for individual GET only select is supported):
| parameter | function |
|---|---|
| top | the number of records to return (maximum 100) |
| skip | the number of records to skip |
| filter | filter expression to apply to the result set |
| orderby | sorting expression |
| select | fields to include (when specified only requested fields will be returned) |
Paging
By default the first page of 100 records is returned if the paging parameters are not specified. Use skip parameter to choose the page and control the page size with top parameter:
| /deal-lines | returns first 100 results |
| /deal-lines?skip=100 | returns 2nd page (next 100 results) |
| /deal-lines?skip=200 | returns 3rd page |
| /deal-lines?top=10&skip=100 | returns 11th page using 10 records per page |
Filtering
Filter expressions are specified using filter parameter. The following comparison and logical operations are provided:
| Operator | Definition |
|---|---|
| eq | equal |
| ne | not equal |
| lt | less than |
| gt | greater than |
| le | less or equal |
| ge | greater or equal |
| and | both must be true |
| or | either is true |
You can combine multiple conditions:
| /deal-lines?filter=state eq 0 | return all records where state equals 0 |
| /deal-lines?filter=state ne 0 | return all records where state is not 0 |
| /deal-lines?filter=state eq 0 and modified_date gt 2018-01-31 | return all records where state equals 0 and modified_date is after Jan 31 2018 |
| /deal-lines?filter=(state eq 0 or state eq 1) and modified_date gt 2018-01-31 | same as above but state can be either 0 or 1 |
You can use the special value of "null" to search for null records: /deal-lines?filter=rate_card_id eq null
The query expressions should be URL encoded. This is important when you need to include special characters, such as "+" (which when encoded will be replaced with "%2B").
If a value contains one or more spaces enclose it in single or double quotes: /deal-lines?filter=line_type.value eq "Out of Contract"
When filtering on system dates (SystemDateTime type) you can include the timezone information and the API will convert it to UTC when applying the filter. For all other date types the timezone information is ignored.
Sorting
You can specify the fields to sort on using orderby parameter. Sorting can be done on more than one field, in either ascending or descending order. Multiple fields should be separated by comma:
| /deal-lines?orderby=id | sort by id |
| /deal-lines?orderby=id asc | same as above |
| /deal-lines?orderby=id desc | sort by id in descending order |
| /deal-lines?orderby=modified_date,id desc | sort by modified_date (ascending) and id (descending) |
Selecting values
You can select which values to return by using "select" parameter. It should be a comma separated list of fields you'd like to include in the response:
| /deal-lines?select=selling_rate,modified_date | include 2 fields |
| /deal-lines?select=selling_rate | include 1 field |
Limiting the fields to only the ones you are interested in is a good way to improve the efficiency when working with the API.
Select supports a special value null - when included it will return every entity field (or every selected field) even if its value is null. You can use it together with regular field names: /deal-lines?select=created_date,null,modified_date
id field is always included.
Combining query parameters
You can combine multiple query parameters to further refine your request:
| /deal-lines?filter=modified_date ge 2018-03-01&orderby=modified_date | request records that were modified on or after Mar 1, 2018 and sort them by modified_date |
| /deal-lines?filter=modified_date ge 2018-03-01&orderby=modified_date&skip=100 | 2nd page for the above request |
| /deal-lines?filter=line_type.value eq Contractual&select=deal_id | request deal ids of deal lines with line type of Contractual |
Picklist Values
Picklist fields are returned with both code and value included:
When creating or updating new fields only code is used, value can be included but will be ignored.
When querying on picklist fields you can query on code:
/deal-lines?filter=state.code eq 0
or value:
/deal-lines?filter=state.value eq Active
For convenience if you're querying on code you can omit ".code" and simply use the field name:
/deal-lines?filter=state eq 0
Entity End-Points
Below are a list of commonly available end-points, please contact the KORE team about your use-case to explore potential options.
| Entity | Entity API Name | Database Schema Name |
| Bill Payment | billing-payments | kore_billpayment |
| Bill Type | billing-types | kore_billtype |
| Bills | billings | kore_bill |
| Billing Batches | billing-batches | kore_billbatch |
| Deal Lines | deal-lines | kore_contractline |
| Deal Seasons | deal-seasons | kore_contractseason |
| Deal Sheets | deals | kore_contract |
| Divisions | divisions | kore_division |
| Expenses | expenses | kore_expense |
| Expense Allocations | expense-allocations | kore_expenseallocation |
| Categories | category | kore_category |
| Products | product | kore_product |
| Inventory Items | inventory-items | kore_property |
| Rate Cards | rate-cards | kore_ratecard |
| Roster Relationships | deal-rosters | kore_rosterrelationship |
| Seasons | seasons | kore_season |
| Rounds | rounds | kore_round |
| Events | events | kore_event |
| Event Lists | event-lists | kore_eventcategory |