7/15/24, 5:34 PM

GET Data Source

TABLE OF CONTENTS
GET DataSource
GET Response
Data Source Response ()
DataSource ()
Header ()
Row ()
API Usage Example
This request method 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

GET DataSource
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.
Requir
Parameter Name Data Type Description
ed
Your unique Company ID is found on the Organization Settings
CompanyId Integer Yes
page of the secure website.
Your unique Integration Key is found on the Organization Settings
Integrationkey String Yes
page of the secure website.
Name String No The data source name to search for.
Id GUID The unique identifier of the DataSource you wish to retrieve.
or Yes
ExternalId string The external identifier for the DataSource to retrieve.
Whether to return the Rows for this Data Source in the response
Defaults to False
ReturnRows Boolean No
If set to True, then will return Rows in a paginated form, using the PageSize
and PageNo values below
The number of Rows returned per page.
Maximum: 1250
PageSize Integer No Default: 1250

Page size of the returned rows (if rows are being returned).
The page number of the Rows result set that you wish to receive back.
Defaults to 0, the first page of the Row result set.
PageNo Integer No
Page number of the rows result set to return (if rows are being returned).

GET Response
The data returned from a DataSource GET is provided as follows:
Data Source Response (<DataSourceResponse>)
Field Name Data Type Description
DataSource DataSource The Data Source found.

1/8
 7/15/24, 5:34 PM

ResponseStatusResponseStatusContains response errors if any occur – helpful for support and debugging purposes.
DataSource (<DataSource>)
Input NameData TypeDescription
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
Collection of Row items for this Data Source
Rows Collection Is only populated if the ReturnRows request option is set to True.
When populated, this is a paginated result set.
Header (<Header>)
Req
Field Data
uire Description
Name Type
d
Name String Yes Name of this Header.
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
DisplayAt String No
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.
Row (<Row>)
Each Row is a collection of Val (<Val>) items, which are the individual column values for that Row.

API Usage Example

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
https://secure.formsonfire.com:443/api/v2/datasource?Id=1f12e179-2393-4f19-a03b-a96e00XXXX

GET 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>

2/8
 7/15/24, 5:34 PM

<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>

3/8
 7/15/24, 5:34 PM

PUT Data Source

This request method allows you to update Data Sources on the platform.
This enables scenarios where data sets maintained in other systems (e.g., SAP, Salesforce) can
be updated into apps automatically.
Updates to a Data Source will be automatically synchronized to mobile devices by the platform.
Thus, if a Data Source is used in a Form or other Screen type, that Data Source can be kept
continuously up to date via this API.
Currently, Data Sources cannot be deleted nor can they be created by this API – this is to protect
existing Screens that use these Data Sources.
Thus, the Data Source must already exist on our platform and be referenced by its unique
ExternalId for an API update to succeed.
Data Sources have a maximum limit of 50,000 rows. If more rows are required, please contact our
support team.
On the Cloud, this API is available via SSL-secured HTTPS connection using the REST PUT verb:
/api/v2/datasource?format=xml/json
The format query string parameter controls the desired response format. Specify either XML or
JSON.
You may use either JSON or XML formats in your PUT request.
You indicate this by setting the ContentType HTTP header as "application/json" or
"application/xml". If no ContentType is specified, XML format is assumed.
NOTE: All XML formatted requests must specify the following XML namespace in the data
source root element: xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
TABLE OF CONTENTS
PUT Request
Parameters
DataSource ()
Header ()
Row ()
Data Source Response ()
Response Status ()
API Usage Example

PUT Request
You may use either JSON or XML formats in your PUT request. You indicate this by setting the ContentType HTTP
header as "application/json" or "application/xml". If no ContentType is specified, XML format is assumed. The required
parameters for a PUT request to the Data Sources API are outlined below.

4/8
 7/15/24, 5:34 PM

Parameters
DataSource (<DataSource>)
NOTE - All XML formatted requests must specify the following xml namespace in the DataSource root element:
xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
Requi
Name Type Description
red
The unique identifier of the Data Source that this request relates to.
Id GUID ✓
Required if ExternalId is not specified.
Name String The name of the Data Source. The value specified will overwrite the existing Data Source name.
The external ID of the Data Source that this request relates to.
If Id has been specified, then ExternalId will be set if a value is set in this field.
ExternalId String ✓
If the ID has not been specified, this value is required and must match an existing Data Source
External ID.
A collection of Header Items. If not specified then the Headers of the Data Source will not be
Collect updated.
Headers
ion NOTE: The number of Headers must match the number of Val elements found in each Row (if
specified).
A collection of Row Items that will completely replace your current Data Source rows.
A limit of 10,000 Rows applies for replacement operations. To add further rows, use further calls to
Collect
Rows add rows incrementally via the NewRows property.
ion
The order of the Rows is the order that the rows will be displayed on the platform.
If you specify Rows, then any values in NewRows and DeletedRows will be ignored.
A collection of Row Items that should be added/updated onto the existing Data Source rows.
Collect
NewRows Use this field to perform incremental inserts/updates of your Data Source.
ion
A limit of 1,500 New Rows applies per request.
A collection of Row Items that should be deleted from the existing Data Source rows.
DeletedR Collect Use this field to perform incremental deletes of your Data Source.
ows ion A limit of 500 Deleted Rows applies per request.
Each Row should contain a single Val element that is your unique identifier for the Row to delete.
CompanyI
Integer Your unique Company ID is found on the Company Setup page of the secure website. ✓
d
Integratio
String Your unique Integration Key is found on the Company Setup page of the secure website. ✓
nKey
Header (<Header>)
Typ Requi
Name Description
e red
Stri
Name Name of this Header ✓
ng
Specifies the desired app display position of this column’s values in each Data Source row.
Options available are:
Displa Stri Title – The main title area of the row
yAt ng 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.
NOTE: It is CRITICALLY important that you include AlL headers for all of your columns in
the Header section of your JSON body. Failure to do this will result in the omitted column
header names being deleted from your Data Source.
Row (<Row>)
Each Row is a collection of Val (<Val>) items, which are the individual column values for that Row. Every Row must
contain at least two Vals and must have as many Vals as there are Headers (columns).

5/8
 7/15/24, 5:34 PM

The first Val should be the unique identifier or key that will be used as the answer value should this Data Source row be
selected in a Form. The first Val is also critical as the key for performing incremental deletes through the DeletedRows
field mentioned above.
The second Val should be the default displayable label text of the row. You can override this default by configuring the
Display Options field in the Data Source "Settings" page of the secure website.
Nam Require
Type Description
e d
A column value for this row can contain any string value.

Strin If you want this column to display an icon/image in the mobile app, then specify an HTTP URL to the
Val
g image in question.
The image linked must be in PNG or JPG/JPEG format.
See the example below for this.
PUT Response
If the PUT update is successful, a 200 HTTP status is returned with an empty response. If the PUT is unsuccessful, a
400 HTTP status is returned along with a DataSourceResponse.
Data Source Response (<DataSourceResponse>)
Input Name Data TypeDescription
ResponseStatusCollection A collection containing the errors that occurred.
Response Status (<ResponseStatus>)
Input NameData TypeDescription
ErrorCode String The error code/message for the failure
Message String Description of the error
Errors Collection Any other inner errors. For Data Sources, this is always empty and can be ignored.

API Usage Example

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.
PUT Request ADDING 1 row - JSON
{
"ExternalId": "my_datasource_extId",
"Headers": [
{
"Name": "ID",
"DisplayAt": "SubLeft"
},
{
"Name": "Title",
"DisplayAt": "Title"
},
{
"Name": "Description",
"DisplayAt": "None"
}
],
"NewRows": [
[
"1",

6/8
 7/15/24, 5:34 PM

"MyTitle1",
"My description1 that must be inserted"
]
],
"CompanyId": CompIdNumber,
"IntegrationKey": "yourCompanyIntegrationKey"
}

PUT Request adding more than 1 row - JSON

"NewRows": [
[
"1",
"MyTitle1",
"My description1 that must be inserted"
],
[
"2",
"MyTitle2",
"My description2 that must be inserted"
],
[
"3",
"MyTitle3",
"My description3 that must be inserted"
]
],

PUT Request – XML

PUT https://secure.formsonfire.com/api/v2/DataSource?format=xml
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>

<DataSource>
<CompanyId>1</CompanyId>
<IntegrationKey>xxxxxxxxxxxxxxx</IntegrationKey>
<Name>Favorite Sports</Name>
<ExternalId>SPORTS-001</ExternalId>
<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>

7/8
 7/15/24, 5:34 PM

<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 />
</Row>
</Rows>
</DataSource>

PUT Response – XML (Error example)

HTTP/1.1 400 Bad Request
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>

<DataSourceResponse>
<ResponseStatus>
<ErrorCode>ArgumentException</ErrorCode>
<Errors />
<Message>Missing parameters</Message>
</ResponseStatus>
</DataSourceResponse>

8/8