The Data Source API allows you to retrieve a Data Source from the platform. On the Cloud, this API is available via SSL-secured HTTPS connection using the REST GET verb.
The format query string parameter controls the desired response format. Specify either xml or json.
/api/v2/datasource?format=xml/json
The GET verb allows you to retrieve a single DataSource, identified by its unique ID. The required and optional parameters for a GET call to the DataSource API are outlined below.
| Parameter Name | Data Type | Required | Description |
| CompanyId | Integer | Yes | Your unique Company Id found on the Organization Settings page of the secure website |
| Integrationkey | String | Yes | Your unique Integration Key found on the Organization Settings page of the secure website |
| Id or ExternalId | GUID string | Yes | The unique identifier of the DataSource you wish to retrieve The external identifier for the DataSource to retrieve |
| ReturnRows | Boolean | No | Whether to return the Rows for this Data Source in the response
|
| PageSize | Integer | No | The page number of the Rows result set that you wish to receive back
|
| PageNo | Integer | No | The number of Rows returned per page
|
The data returned from a DataSource GET is provided as follows:
| Field Name | Data Type | Description |
| DataSource | DataSource | The Data Source found |
| ResponseStatus | ResponseStatus | Contains response errors if any occur – helpful for support and debugging purposes |
| Input Name | Data Type | Description |
| Id | GUID | The unique identifier of this Data Source |
| ExternalId | String | The external Id of the Data Source |
| CompanyId | Integer | Unique organization identifier of this Data Source |
| Name | String | The name of the Data Source. |
| Headers | Collection | A collection of Header Items. |
| TotalRows | Integer | The total number of Rows in this Data Source |
| Rows | Collection | Collection of Row items for this Data Source Is only populated if the ReturnRows request option is set to True. When populated, this is a paginated result set. |
| Field Name | Data Type | Required | Description |
| Name | String | Yes | Name of this Header |
| DisplayAt | String | No | Specifies the desired app display position of this column’s values in each Data Source row. Options available are: Title – The main title area of the row SubLeft – Appears below the Title in smaller text Thumb – Displays the column value as an image thumbnail to the left of the Title. Only applicable if your column values are http URLs pointing at PNG or JPG files. |
Each Row is a collection of Val (<Val>) items, which are the individual column values for that Row.
Given that the API is REST-based, you can access the API directly via your web browser to test it using a REST plugin like the Postman plugin for Google Chrome.
GET Request – XML
GET /api/v2/datasource?externalid=SPORTS-001&integrationkey=xxxxxxxxxxxx&companyid=1&format=xml&returnrows=true&pageno=0&pagesize=100GET Response - XML
<DataSource> <Id>XXXXX</Id> <CompanyId>1</CompanyId> <Name>Favorite Sports</Name> <ExternalId>SPORTS-001</ExternalId> <Headers> <Header> <Name>Sport Code</Name> <DisplayAt>Title</DisplayAt> </Header> <Header> <Name>Sport Name</Name> </Header> <Header> <Name>Description</Name> </Header> <Header> <Name>Image</Name> <DisplayAt>Thumb</DisplayAt> </Header> </Headers> <TotalRows>3</TotalRows> <Rows> <Row> <Val>AH</Val> <Val>Air Hockey</Val> <Val>This is some additional information about Air Hockey</Val> <Val>http://mywebsite.com/images/air-hockey.jpg</Val> </Row> <Row> <Val>FB</Val> <Val>Football</Val> <Val>This is some additional information about Football</Val> <Val>http://mywebsite.com/images/football.jpg</Val> </Row> <Row> <Val>CH</Val> <Val>Chess (We have no additional info or images for this sport)</Val> <Val></Val> <Val></Val> </Row> </Rows> </SList>