Introduction

The Onspring API is organized around REST. It enables external programs to retrieve, save, and delete data within your Onspring instance. The Onspring API does not support bulk operations.

Note: There is a newer version of the Onspring API available here. If you are using the Onspring API for the first time, we recommend using the most recent version.

Base URL

The base url for the Onspring API will be the same for all instances regardless of whether the instances is a development, test, or production instance. The routing of the request to the correct instance be based on the API key provided in the request.

BASE URL

Click to Copy

https://api.onspring.com/v1

Client SDKs

Official

dotnet add package Onspring.API.SDK --version 2.1.0

Authentication

The Onpsring API uses API keys to authenticate requests. These keys are specific to a given Onspring instance. You can view and manage your API keys from within your instance.

An API key needs to be provided with every request. This is done by adding the X-ApiKey header to the request. The API key provided should be in an Enabled status and it should be assigned a role that has the proper permissions for the request made by the API key. The role assigned should also be in an Active status.

If the role assigned to the API key does not have sufficient permissions to perform the requested action or is in n Inactive status, an error will be returned. Onspring administrators may configure roles for API keys just as they would any other role in Onspring. However each API key can have only one assigned role.

X-ApiKey Header

API Keys are specific to an instance. If you are using the API to access data from multiple instances, you will need to create an API key for each instance.

X-APIKEY

Click to Copy

X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000

Dates and Times

Onspring stores date/time information in UTC (Coordinated Universal Time), and the API expects to pass UTC data back and forth. The Onspring GUI converts the UTC value to the appropriate display value depending on your instance configuration and a user's profile settings. This means that when you are working with dates and times via the API, you need to be expecting to send and receive dates in UTC.

Retrieving and sending date field values

DATE FIELD VALUE

Click to Copy

{
  "Type": 3,
  "FieldId": 4800,
  "Value": "2023-04-22T05:00:00Z"
}

VALUE FOR DATE FIELD

Click to Copy

{
  "4800": "2023-04-22T05:00:00Z"
}

Record Id

The Record Id is a unique identifier for a record in an Onspring app. You will use the Record Id to retrieve, update, and delete records. However you should not confuse this Record Id with the value that is held and displayed in the Record Id field within the Onspring GUI. The value held in the Record Id field is also a unique identifier for a record in an Onspring app, but it is not guaranteed to be the same as the value of the Record Id property returned via the API.

For the purpose of clarity it can be helpful to think of the Record Id value retrieved via the API as being the record's internal identifier, and the value held in the Record Id field as being the record's external identifier. The internal Record Id is the value you will want to use at all times when working with records via the API. The external Record Id is only useful when working with records via the Onspring GUI.

If you are ever encountering an anomaly where the data being retrieved or updated via the API does not match the data being displayed in the Onspring GUI, you will want to make sure that you are not using the Record Id field value to identify the record to be retrieved or updated.

Note: The internal Record Id is the value that will be used to represent records in a reference field value.

Internal Record Id vs External Record Id

RECORD

Click to Copy

{
  "AppId": 130,
  "RecordId": 11, // Internal Record Id
  "FieldData": [
    {
      "Type": 1,
      "FieldId": 4745, // External Record Id
      "Value": 11
    }
  ]
}

Error Handling

The Onspring API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error within Onspring's servers.

The internet is a big place and requests sent across the network should be treated as if they may fail at any time. We recommend that you implement a retry strategy for requests that fail. This will help to ensure that your application is able to recover from any network issues that may occur.

Some 4xx errors will also include an Error object in the response body. This object can contain a message with additional information about the error.

Note: The exception to the above is if you receive a 499 status code this indicates that the request has exceeded the 90 second timeout limit of our api gateway. This is not an error with the request itself, but rather a timeout. This is a result of the request taking too long to process. Typically this is due to a large amount of data being requested or a request triggering a lot of processing. If you receive this error, you should consider breaking up your request into smaller requests.

Error Properties

Property Name	Data Type	Description
Message	`string`	A human-readable message describing the error.

Error Code Summary

ERROR CODES

Click to Copy

400 Bad Request - The request was unacceptable, often due to missing a required parameter.
401 Unauthorized - No valid API key provided.
403 Forbidden - The API key doesn't have permissions to perform the request.
404 Not Found - The requested resource doesn't exist.
499 Client Closed Request - Our API gateway closed the connection because the request exceeded the 90 second timeout limit.
5xx Server Errors - Something went wrong on Onspring's end.

The Error Object

ERROR OBJECT

Click to Copy

{
  "Message": "Client does not have access to read app: 1"
}

Connectivity

This endpoint allows you to verify that you are able to connect to the Onspring API. When successful, a 204 response will be returned with no body.

Checking for connection to the api

GET /Ping

Click to Copy

curl --location 'https://api.onspring.com/v1/Ping' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

Apps

These are objects that represent apps and/or surveys in an Onspring instance. You can retrieve a list of apps that the given API Key has access to.

App Properties

Property Name	Data Type	Description
Id	`number`	The id of the app.
Name	`string`	The name of the app.

The App Object

APP

Click to Copy

{
  "Id": 195,
  "Name": "Tasks"
}

Get Apps

This endpoint returns an array of apps that the given API key can access.

Retrieve apps accessible to the API key

GET /Apps

Click to Copy

curl --location 'https://api.onspring.com/v1/Apps' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

RESPONSE

Click to Copy

[
  {
    "Id": 195,
    "Name": "Tasks"
  }
]

Reports

These are objects that represent reports and their data for apps and surveys in an Onspring instance. You can retrieve a list of reports for an app or survey, or get a specific report's data.

Report Properties

Property Name	Data Type	Description
AppId	`number`	The id of the app or survey that the report belongs to.
Id	`number`	The id of the report.
Name	`string`	The name of the report.

The Report Object

REPORT

Click to Copy

{
  "AppId": 195,
  "Id": 613,
  "Name": "Test 1"
}

Report Data

These are objects that represent the data for a report in an Onspring instance. They will be returned when you request a specific report by id.

Report Data Properties

Property Name	Data Type	Description
Columns	`string[]`	The names of the fields in the report.
Rows	`object[][]`	The data for each row in the report.

The Report Data Object

REPORT DATA

Click to Copy

{
  "Columns": [
    "Name",
    "Owner",
    "Due Date",
    "Status",
    "Description"
  ],
  "Rows": [
    [
      "A New Test Task",
      null,
      null,
      null,
      "<p>This is a test task.</p>"
    ]
  ]
}

Report Data Format

When retrieving data for reports via the Onspring API using certain endpoints you can specify the format of the data being retrieved. The format will be specified in a query parameter. These endpoints are:

Get Report by Id

The format values can be either Raw or Formatted. If the format is not specified then the default format is Raw. The format specified will be applied to all the data being retrieved. The impact of the format on the data retrieve will depend on the type of field. The following tables shows the impact of the format on the data retrieved for each field type.

Raw Format

Field Type	Return Data Type	Description
Attachment	`string`	A pipe (\|) separated list of file names.
AutoNumber	`number`	The field value will be returned as a number.
Date/Time	`string`	The field value will be returned as a string in the format `m/d/yyyy h:mm tt`.
Image	`string`	A pipe (\|) separated list of file names.
List	`string`	A pipe (\|) separated list of list value names.
Matrix	`string`	A pipe (\|) separated list of matrix values in the format "row list value name / column list value name".
Number	`number`	The field value will be returned as a number.
Reference	`string`	A pipe (\|) separated list of display link field values.
Survey Campaign	`string`	The campaign name.
Survey Group Scoring	`string`	A pipe (\|) separated list of survey scoring groups in the format "group name: group value"
Text	`string`	The field value will be returned as a string including any HTML markup.
Time Span	`string`	The field value will be returned as a string which represents the time span entered.

Formatted Format

Field Type	Return Data Type	Description
Attachment	`string`	A newline (\r\n) separated list of file names.
AutoNumber	`string`	The field value will be returned as a string including any configured formatting.
Date/Time	`string`	The field value will be returned as a string including any configured formatting.
Image	`string`	A newline (\r\n) separated list of file names.
List	`string`	A newline (\r\n) separated list of list value names.
Matrix	`string`	A newline (\r\n) separated list of matrix values in the format "row list value name / column list value name".
Number	`string`	The field value will be returned as a string including any configured formatting.
Reference	`string`	A newline (\r\n) separated list of display link field values.
Survey Campaign	`string`	The campaign name.
Survey Group Scoring	`string`	A newline (\r\n) separated list of survey scoring groups in the format "group name: group value"
Text	`string`	The field value will be returned as a string excluding any HTML markup.
Time Span	`string`	The field value will be returned as a string which represents the time span entered.

The Values in a Raw Response

RAW

Click to Copy

{
  "Columns": [
    "attachment_field",
    "Record Id",
    "Created Date",
    "image_field",
    "multi_select_list_field",
    "matrix_survey_answer_field",
    "number_field",
    "multi_select_reference_field",
    "Survey Campaign",
    "Group Scoring",
    "multi_line_text_field",
    "time_span_field_with_recurrence"
  ],
  "Rows": [
    [
      "test-attachment.txt|odin-project-timestamps.txt|test-attachment.txt|test-attachment.txt|test-attachment.txt|test-attachment.txt|test-attachment.txt|test-attachment.txt|test-attachment.txt",
      1,
      "2/16/2023 5:14 AM",
      "test-image.png|test-image.jpg",
      "list_value_1|list_value_2",
      "thing_1 / no|thing_2 / no",
      100.0,
      "Changed|Test",
      "targeted_recipient_campaign",
      "scoring_group_list_1: 5|scoring_group_list_2: 3|scoring_group_list_3: 7",
      "<p>This is a test</p>",
      "Every 11 Second(s) End After 1 Occurrences"
    ]
  ]
}

The Values in a Formatted Response

FORMATTED

Click to Copy

{
  "Columns": [
    "attachment_field",
    "Record Id",
    "Created Date",
    "image_field",
    "multi_select_list_field",
    "matrix_survey_answer_field",
    "number_field",
    "multi_select_reference_field",
    "Survey Campaign",
    "Group Scoring",
    "multi_line_text_field",
    "time_span_field_with_recurrence"
  ],
  "Rows": [
    [
      "test-attachment.txt\r\nodin-project-timestamps.txt\r\ntest-attachment.txt\r\ntest-attachment.txt\r\ntest-attachment.txt\r\ntest-attachment.txt\r\ntest-attachment.txt\r\ntest-attachment.txt\r\ntest-attachment.txt",
      "recordId-1",
      "2/16/2023 5:14 AM",
      "test-image.png\r\ntest-image.jpg",
      "list_value_1\r\nlist_value_2",
      "thing_1 / no\r\nthing_2 / no",
      "$100 dollars",
      "Changed\r\nTest",
      "targeted_recipient_campaign",
      "scoring_group_list_1: 5\r\nscoring_group_list_2: 3\r\nscoring_group_list_3: 7",
      "This is a test",
      "Every 11 Second(s) End After 1 Occurrences"
    ]
  ]
}

Get Reports by App

This endpoint returns an array of reports for the given app.

Query Parameters

Parameter Name	Data Type	Description
appId	`number`	The id of the app to retrieve reports for.

Retrieving reports for the given app

GET /Reports

Click to Copy

curl --location 'https://api.onspring.com/v1/Reports?appId=195' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \

RESPONSE

Click to Copy

[
  {
    "AppId": 195,
    "Id": 613,
    "Name": "Test 1"
  }
]

Get Report by Id

This endpoint returns the Report Data for the given report.

Path Parameters

Property Name	Data Type	Description
reportId	`number`	The id of the report.

Query Parameters

Property Name	Data Type	Description
dataFormat	`string`	The format of the field data in the response. Valid values are `Raw` and `Formatted`. If not specified, `Raw` will be used.
dataType	`string`	Indicate whether you want the report's report data or its chart data returned. Valid values are `ReportData` and `ChartData`. If not specified, `ReportData` will be used.

Retrieving data from a report

GET /Reports/{reportId}

Click to Copy

curl --location 'https://api.onspring.com/Reports/613' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

RESPONSE

Click to Copy

{
  "Columns": [
    "Name",
    "Owner",
    "Due Date",
    "Status",
    "Description"
  ],
  "Rows": [
    [
      "A New Test Task",
      null,
      null,
      null,
      "<p>This is a test task.</p>"
    ],
    [
      "A New Test Task",
      "Severus",
      "12/25/2021 12:00 AM",
      "In Progress",
      "<p>This is a test task.</p>"
    ]
  ]
}

Fields

These are objects representing a field in an app or survey in your instance. You can retrieve a list of fields in an app or survey or retrieve a specific field to see the properties of the field(s).

Field Properties

Property Name	Data Type	Description
Id	`number`	The id of the field.
AppId	`number`	The id of the app or survey.
Name	`string`	The name of the field.
Type	`number`	The type of the field. Possible values are: `100`, `200`, `204`, `300`, `307`, `400`, `500`, `502`, `600`, `601`, `602`, `800`, `801`, or `900`.
Status	`number`	The status of the field. Possible values are: `0` or `1`.
IsRequired	`boolean`	Indicates whether the field is configured to be required.
IsUnique	`boolean`	Indicates whether the field is configured to be unique.

Field Types

Type Value	Description
100	Attachment Field
200	Number Field
204	Auto Number Field
300	Date/Time Field
307	Time Span Field
400	List Field
500	Reference or Parallel Reference Field
502	Survey Reference Field
600	Survey Scoring Group Field
601	Survey Campaign Field
602	Survey Unified Answer Field
800	Attachment Field
801	Image Field
900	Formula Field

Field Statuses

Status Value	Description
0	Enabled
1	Disabled

The Field Object

FIELD

Click to Copy

{
  "Id": 6983,
  "AppId": 195,
  "Name": "Name",
  "Type": 100,
  "Status": 0,
  "IsRequired": false,
  "IsUnique": false
}

Formula Field

Formula fields are a special type of field that can be used to calculate values based on other fields. These fields can have different output types and therefore have the following additional properties in addition to the standard Field properties.

Formula Field Properties

Property Name	Data Type	Description
outputType	`number`	Indicates the type of the output of the formula field. Possible values are: `0`,`1`, `2`, or `3`.
values	`object[]`	An array of List Value objects that define the possible values of the formula field. This array will only be populated with values if the `outputType` is set to `ListValue`.

Formula Field Output Types

Output Type Value	Output Type Description
0	Text
1	Numeric
2	Date/Time
3	List Value

The Formula Field Object

FORMULA FIELD

Click to Copy

{
  "OutputType": 3,
  "Values": [
    {
      "Id": "b235afb2-b786-4c87-bce9-fbd700e246c1",
      "Name": "list_value_1",
      "SortOrder": 1,
      "NumericValue": 1,
      "Color": "#6dcff6"
    },
    {
      "Id": "5cd7cd55-d6a6-40e0-a560-8aa407c13210",
      "Name": "list_value_2",
      "SortOrder": 2,
      "NumericValue": 2,
      "Color": "#8e468e"
    }
  ],
  "Id": 4815,
  "AppId": 130,
  "Name": "list_formula_field",
  "Type": 900,
  "Status": 0,
  "IsRequired": false,
  "IsUnique": false
}

Reference Field

Reference fields are a special type of field that allow you to create relationships between one or more content records. These fields have the following additional properties in addition to the standard Field properties.

Reference Field Properties

Property Name	Data Type	Description
multiplicity	`number`	Indicates whether the field is single or multi select. Possible values are: `0` or `1`.

Multiplicity Types

Multiplicity Type Value	Multiplicity Type Description
0	Indicates the reference field is single select and will only ever hold one value.
1	Indicates the reference field is multi select and can contain more than one value.

The Reference Field Object

REFERENCE FIELD

Click to Copy

{
  "Multiplicity": 1,
  "Id": 4808,
  "AppId": 130,
  "Name": "multi_select_reference_field",
  "Type": 500,
  "Status": 0,
  "IsRequired": false,
  "IsUnique": false
}

List Field

List fields are a special type of field that allow you to define a list of values that can be selected for the field. These fields have the following additional properties in addition to the standard Field properties.

List Field Properties

Property Name	Data Type	Description
Multiplicity	`number`	Indicates whether the field is single or multi select. Possible values are: `0` or `1`.
Values	`object[]`	An array of List Value objects that define the possible values of the list field.

Multiplicity Types

Multiplicity Type Value	Multiplicity Type Description
0	Indicates the reference field is single select and will only ever hold one value.
1	Indicates the reference field is multi select and can contain more than one value.

The List Field Object

LIST FIELD

Click to Copy

{
  "Multiplicity": 0,
  "Values": [
    {
      "Id": "2c1af5b1-0f90-4378-b9a5-8b7e22f2bc84",
      "Name": "list_value_1",
      "SortOrder": 1,
      "NumericValue": 1.0,
      "Color": "#008e8e"
    },
    {
      "Id": "0421e502-7f76-480a-9311-363aca3560bc",
      "Name": "list_value_2",
      "SortOrder": 2,
      "NumericValue": 2.0,
      "Color": "#a186be"
    },
    {
      "Id": "285b91c1-5800-47cb-a030-8cf7cdd7cdf1",
      "Name": "updated_list_value_1676840661138}",
      "SortOrder": 3,
      "NumericValue": 1.0,
      "Color": "#000000"
    }
  ],
  "Id": 4801,
  "AppId": 130,
  "Name": "single_select_list_field",
  "Type": 400,
  "Status": 0,
  "IsRequired": false,
  "IsUnique": false
}

List Values

These are objects that represent the defined values of a List Field or a Formula Field with a List Value output type.

List Value Properties

Property Name	Data Type	Description
Id	`string`	The unique id of the list value.
Name	`string`	The name of the list value.
SortOrder	`number`	The sort order of the list value.
NumericValue	`number`	The numeric value of the list value.
Color	`string`	The color of the list value.

The List Value Object

LIST VALUE

Click to Copy

{
  "Id": "b235afb2-b786-4c87-bce9-fbd700e246c1",
  "Name": "list_value_1",
  "SortOrder": 1,
  "NumericValue": 1,
  "Color": "#6dcff6"
}

Get Fields by App

This endpoint returns an array of Fields for the given app.

Query Parameters

Parameter Name	Data Type	Description
appId	`number`	The id of the app to retrieve fields for.

Retrieve all fields for an app

GET /Fields

Click to Copy

curl --location 'https://api.onspring.com/v1/Fields?appId=195' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

RESPONSE

Click to Copy

[
  {
    "Id": 6989,
    "AppId": 195,
    "Name": "Attachments",
    "Type": 800,
    "Status": 0,
    "IsRequired": false,
    "IsUnique": false
  },
  {
    "Multiplicity": 0,
    "Id": 6980,
    "AppId": 195,
    "Name": "Created By",
    "Type": 500,
    "Status": 0,
    "IsRequired": false,
    "IsUnique": false
  }
]

Get Field by Id

This endpoint returns a Field by its id.

Path Parameters

Property Name	Data Type	Description
fieldId	`number`	The id of the field to retrieve.

Retrieve a field by its id

GET /Fields/{fieldId}

Click to Copy

curl --location 'https://api.onspring.com/v1/Fields/6986' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

RESPONSE

Click to Copy

{
  "Multiplicity": 0,
  "Values": [
    {
      "Id": "4118d53a-9121-4345-8682-07f23d606daa",
      "Name": "In Progress",
      "SortOrder": 1,
      "NumericValue": 1.0,
      "Color": "#db3e3e"
    },
    {
      "Id": "1c1c5f7e-cd03-4b70-9790-0f83b24b5863",
      "Name": "Complete",
      "SortOrder": 2,
      "NumericValue": 2.0,
      "Color": "#ffffff"
    },
    {
      "Id": "42493542-f77c-4298-91a0-18455ba0c764",
      "Name": "Not Started",
      "SortOrder": 3,
      "NumericValue": 0.0,
      "Color": "#ffffff"
    }
  ],
  "Id": 6986,
  "AppId": 195,
  "Name": "Status",
  "Type": 400,
  "Status": 0,
  "IsRequired": false,
  "IsUnique": false
}

Records

These are objects representing a content record in your instance. You can create new records in your instance, retrieve existing records to see the data that has been entered into a record, you can update a record to change the data in it, and you can delete a record to remove it from the instance.

Record Properties

Property Name	Data Type	Description
AppId	`number`	The id of the app or survey.
RecordId	`number`	The id of the record.
FieldData	`object[]`	An array of Field Value objects.

The Record Object

RECORD

Click to Copy

{
  "AppId": 130,
  "RecordId": 11,
  "FieldData": [
    {
      "Type": 1,
      "FieldId": 4745,
      "Value": 11
    }
  ]
}

Field Values

These are objects representing a field value in a record. They will comprise the fieldData array in a Record object. The type property will determine what the type and structure of the value property will be.

Field Value Properties

Property Name	Data Type	Description
Type	`number`	The type of the field.
FieldId	`number`	The id of the field.
Value	`object`	The value of the field.

Field Value Types

Type	Description	Value Data Type
0	A string value.	`string`
1	An integer value.	`number`
2	A decimal value.	`number`
3	A date value.	`string`
4	A Time Span value.	`object`
5	A GUID value.	`string`
10	A list of string values.	`string[]`
11	A list of integer values.	`number[]`
15	A list of GUID values.	`string[]`
16	A list of Attachment values.	`object[]`
17	A list of Scoring Group values.	`object[]`

Time Span Field Value

Property Name	Data Type	Description
Quantity	`number`	The number of the specified increment.
Increment	`number`	The increment of time. Can be one of the following values: `128`, `64`, `32`, `16`, `8`, `4`, `2`.
Recurrence	`number`	The recurrence of the time span. Can be one of the following values: `0`, `1`, `2`.
EndByDate	`string`	The end date of the time span. This will only be set if `recurrence` is set to `1`.
EndAfterOccurrences	`number`	The number of occurrences of the time span. This will only be set if `recurrence` is set to `2`.

Increment Types

Type Value	Description
2	Seconds
4	Minutes
8	Hours
16	Days
32	Weeks
64	Months
128	Years

Recurrence Types

Type Value	Description
0	None
1	EndByDate
2	EndAfterOccurrences

Attachment Field Value

Property Name	Data Type	Description
FileId	`number`	The id of the file.
FileName	`string`	The name of the file.
Notes	`string`	The notes for the attachment.
StorageLocation	`number`	The storage location of the file. Can be one of the following values: `0`, `1`, `2`.
DownloadLink	`string`	The download link for the file. This will only be returned if the `storageLocation` is not `Internal`.
QuickEditLink	`string`	The quick edit link for the file. This will only be returned if the `storageLocation` is not `Internal`.

Storage Location Types

Type Value	Description
0	Internal
1	OneDrive
2	Google Drive

Scoring Group Field Value

Property Name	Data Type	Description
ListValueId	`string`	The id of the list value.
Name	`string`	The name of the scoring group.
Score	`number`	The score of the scoring group.
MaximumScore	`number`	The maximum score of the scoring group.

The Field Value Object

The following snippet contains an example of field value objects for each of the possible field value types.

FIELD VALUES

Click to Copy

{
  "Type": 1,
  "FieldId": 6976,
  "Value": 1
},
{
  "Type": 3,
  "FieldId": 4746,
  "Value": "2023-02-16T05:14:14Z"
},
{
  "Type": 0,
  "FieldId": 4753,
  "Value": "test@test.com"
},
{
  "Type": 2,
  "FieldId": 4756,
  "Value": 15.3
},
{
  "Type": 17,
  "FieldId": 4762,
  "Value": [
    {
      "listValueId": "c9e4d695-184c-48ec-a8ef-01a52b2bce39",
      "name": "scoring_group_list_1",
      "score": 5,
      "maximumScore": 6
    },
  ]
},
{
  "Type": 11,
  "FieldId": 4792,
  "Value": [
    1,
    2,
  ]
},
{
  "Type": 5,
  "FieldId": 4801,
  "Value": "2c1af5b1-0f90-4378-b9a5-8b7e22f2bc84"
},
{
  "Type": 15,
  "FieldId": 4802,
  "Value": [
    "71afe161-34f9-49d0-b45e-968b764c884c",
    "d40a74dd-abb5-4fbb-82c0-5766e871e2a4"
  ]
},
{
  "Type": 16,
  "FieldId": 4806,
  "Value": [
    {
      "fileId": 909,
      "fileName": "test-attachment.txt",
      "notes": "This is a test",
      "storageLocation": "Internal"
    },
  ]
},
{
  "Type": 4,
  "FieldId": 4811,
  "Value": {
    "quantity": 10,
    "increment": "Minutes",
    "recurrence": "None"
  }
},
{
  "Type": 10,
  "FieldId": 4999,
  "Value": [
    "list_value_1",
    "list_value_2"
  ]
},
{
  "Type": 11,
  "FieldId": 4807,
  "Value": [
    910,
    911,
  ]
}

Record Data Format

When retrieving data for records via the Onspring API using certain endpoints you can specify the format of the data being retrieved. The format will be in a query parameter. These endpoints are:

Get Records by App
Get Record by Id

Raw Format

Field Type	Return Data Type	Description
AutoNumber	`number`	The field value will be returned as a number.
Date/Time	`string`	The field value will be returned as a string in the format `YYYY-MM-DDTHH:MM:SSZ`.
List	`string` or `string[]`	The field value will be returned as a string or an array of strings where the strings are the GUID ids of the selected list items.
Number	`number`	The field value will be returned as a number.
Text	`string`	The field value will be returned as a string including any HTML markup.
Time Span	`object`	The field value will be returned as a Time Span object.

Formatted Format

Field Type	Return Data Type	Description
AutoNumber	`string`	The field value will be returned as a string including any configured formatting.
Date/Time	`string`	The field value will be returned as a string including any configured formatting.
List	`string` or `string[]`	The field value will be returned as a string or an array of strings where the strings are the names of the selected list items.
Number	`string`	The field value will be returned as a string including any configured formatting.
Text	`string`	The field value will be returned as a string without any HTML markup.
Time Span	`string`	The field value will be returned as a string which represents the time span entered.

The Values in a Raw Response

RAW

Click to Copy

{
  "AppId": 130,
  "RecordId": 11,
  "FieldData": [
    {
      "Type": 1,
      "FieldId": 4745, // AutoNumber Field
      "Value": 11
    },
    {
      "Type": 3,
      "FieldId": 4800, // Date/Time Field
      "Value": "2023-04-22T05:00:00Z"
    },
    {
      "Type": 5,
      "FieldId": 4801, // Single Select List Field
      "Value": "2c1af5b1-0f90-4378-b9a5-8b7e22f2bc84"
    },
    {
      "Type": 15,
      "FieldId": 4802, // Multi Select List Field
      "Value": [
        "71afe161-34f9-49d0-b45e-968b764c884c",
        "d40a74dd-abb5-4fbb-82c0-5766e871e2a4"
      ]
    },
    {
      "Type": 2,
      "FieldId": 4803, // Number Field
      "Value": 10.0
    },
    {
      "Type": 0,
      "FieldId": 4805, // Text Field
      "Value": "<p>This is a test</p>"
    },
    {
      "Type": 4,
      "FieldId": 4810, // TimeSpan Field
      "Value": {
        "Quantity": 1.0,
        "Increment": 2,
        "Recurrence": 2,
        "EndByDate": null,
        "EndAfterOccurrences": 1
      }
    }
  ]
}

The Values in a Formatted Response

RAW

Click to Copy

{
  "AppId": 130,
  "RecordId": 11,
  "FieldData": [
    {
      "Type": 0,
      "FieldId": 4745, // AutoNumber Field
      "Value": "recordId-11"
    },
    {
      "Type": 0,
      "FieldId": 4800, // Date/Time Field
      "Value": "Saturday, April 22, 2023 5:00 AM"
    },
    {
      "Type": 0,
      "FieldId": 4801, // Single Select List Field
      "Value": "list_value_1"
    },
    {
      "Type": 10,
      "FieldId": 4802, // Multi Select List Field
      "Value": ["list_value_1", "list_value_2"]
    },
    {
      "Type": 0,
      "FieldId": 4803, // Number Field
      "Value": "$10 dollars"
    },
    {
      "Type": 0,
      "FieldId": 4805, // Text Field
      "Value": "This is a test"
    },
    {
      "Type": 0,
      "FieldId": 4810, // TimeSpan Field
      "Value": "Every 1 Second(s) End After 1 Occurrences"
    }
  ]
}

Get Records by App

This endpoint returns an array of records for a given app or survey.

Path Parameters

Parameter Name	Data Type	Description
appId	`number`	The id of the app or survey that contains the records.

Query Parameters

Parameter Name	Data Type	Description
fieldIds	`string`	A comma-separated list of field ids to include in the response. If not specified, all fields will be returned.
records	`string`	A comma-separated list of records ids to include in the response. If not specified, all records will be returned.
$filter	`string`	A filter expression that will be used to filter the records returned.
dataFormat	`string`	The format of the field data in the response. Valid values are `Raw` and `Formatted`. If not specified, `Raw` will be used.

Filter

A filter expression is a string that is used to filter records returned. The filter operators available, the fields they are applicable to, and the syntax for each operator are described below.

Operator	Description	Applicable Fields
eq	Determines if the field equals a value.	`Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`.
ne	Determines if the field does not equal a value.	`Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`.
lt	Determines if the field is less than a value.	`Number`, `date`, and `auto-number` fields and formula fields that have an output type of `number` or `date`.
gt	Determines if the field is greater than a value.	`Number`, `date`, and `auto-number` fields and formula fields that have an output type of `number` or `date`.

Delimiters

When using a string value in a filter expression you must use single quotes (') to delimit the string value. When using a date value in a filter expression you must use single quotes (') to delimit the date value and the delimited value should be preceded by the word datetime.

Combining Filters

You can combine multiple filters using the and and or operators as well as parentheses to control the order of operations. The not operator can be used to negate a filter.

Retrieving records for an app

GET /Records/{appId}

Click to Copy

curl --location 'https://api.onspring.com/v1/Records/195?%24filter=not%20(6987%20lt%2010%20or%206986%20eq%20%27In%20Progress%27)%20and%206985%20gt%20datetime%272014-03-01T00%3A00%3A00.0000000%27&recordIds=5%2C100%2C101%2C102&fieldIds=6983%2C6986%2C6987%2C6985%2C6984&dataFormat=Formatted' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

RESPONSE

Click to Copy

[
  {
    "AppId": 195,
    "RecordId": 5,
    "FieldData": [
      {
        "Type": 0,
        "FieldId": 6983,
        "Value": "Test Task 5"
      },
      {
        "Type": 0,
        "FieldId": 6986,
        "Value": "Complete"
      },
      {
        "Type": "Integer",
        "FieldId": 6987,
        "Value": 2
      },
      {
        "Type": 0,
        "FieldId": 6985,
        "Value": "12/31/2021 6:00 AM"
      },
      {
        "Type": 0,
        "FieldId": 6984,
        "Value": "This is a test!"
      }
    ]
  }
]

Get Record by Id

This endpoint returns a single record based on the given record id.

Path Parameters

Parameter Name	Data Type	Description
appId	`number`	The id of the app or survey that contains the record.
recordId	`number`	The id of the record.

Query Parameters

Parameter Name	Data Type	Description
fieldIds	`string`	A comma-separated list of field ids to include in the response. If not specified, all fields will be returned.
dataFormat	`string`	The format of the field data in the response. Valid values are `Raw` and `Formatted`. If not specified, `Raw` will be used.

Retrieving a record from an app

GET /Records/{appId}/{recordId}

Click to Copy

curl --location 'https://api.onspring.com/v1/Records/195/1?fieldIds=6976&dataFormat=Raw' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

RESPONSE

Click to Copy

{
  "AppId": 195,
  "RecordId": 1,
  "FieldData": [
    {
      "Type": 1,
      "FieldId": 6976,
      "Value": 1
    }
  ]
}

Add Record

This endpoint allows you to add a record to an app. If the record creation was successful a 201 response will be returned.

Path Parameters

Parameter Name	Data Type	Description
appId	`number`	The id of the app or survey that the record will be added to.

Request Body Properties

Property Name	Data Type	Description
FieldData	`object`	The field data to be included in the record when added. Each `key` should be an id of a field you want to populate and its `value` should be the value you want to place into that field.

Response Body Properties

Property Name	Data Type	Description
recordId	`number`	The record id of the newly created record.
Warnings	`string[]`	A list of warnings related to the records creation. Will only be present if warnings were in fact generated by the request.

Add a record in an app

POST /Records/{appId}

Click to Copy

curl --location 'https://api.onspring.com/v1/Records/195' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
--header 'Content-Type: application/json' \
--data '{
  "FieldData": {
    "6983": "A New Test Task",
    "6984": "This is a test task.",
    "6985": "12/25/2021",
    "6986: "4118d53a-9121-4345-8682-07f23d606daa",
    "6987": [4]
  }
}'

RESPONSE

Click to Copy

{
  "recordId": 781,
  "Warnings": ["A warning"]
}

Update Record

This endpoint allows you to update a record in an app. If the record update is successful and no warnings are encountered a 204 response will be returned with an empty body. If warnings are encountered a 200 response will be returned with the body containing the warnings encountered.

Path Parameters

Parameter Name	Data Type	Description
appId	`number`	The id of the app or survey that contains the record to be updated.
recordId	`number`	The id of the record that will be updated.

Request Body Properties

Property Name	Data Type	Description
FieldData	`object`	The field data to be used to update the record. Each `key` should be an id of a field you want to populate and its `value` should be the value you want to place into that field.

Response Body Properties

Property Name	Data Type	Description
Warnings	`string[]`	A list of warnings related to the records creation. Will only be present if warnings were in fact generated by the request.

Update a record in an app

PUT /Records/{appId}/{recordId}

Click to Copy

curl --location --request PUT 'https://api.onspring.com/v1/Records/195/12' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
--header 'Content-Type: application/json' \
--data '{
  "FieldData": {
    "6983": "An Updated Test Task",
    "6984": "This is a test task.",
    "6985": "12/25/2021",
    "6986: "4118d53a-9121-4345-8682-07f23d606daa",
    "6987": [4]
  }
}'

RESPONSE

Click to Copy

{
  "Warnings": ["A warning"]
}

Delete Record

This endpoint allows you to delete a record in an app. If the record deletion is successful a 204 response will be returned with an empty body.

Path Parameters

Parameter Name	Data Type	Description
appId	`number`	The id of the app or survey that contains the record to be deleted.
recordId	`number`	The id of the record that will be deleted.

Delete a record in an app

DELETE /Records/{appId}/{recordId}

Click to Copy

curl --location --request DELETE 'https://api.onspring.com/v1/Records/195/12' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

Get File

This endpoint allows you to retrieve a file that is held in an attachment or image field on a record in an app.

Path Parameters

Parameter Name	Data Type	Description
appId	`number`	The id of the app or survey where the file is held.
recordId	`number`	The id of the record where the file is held.
fieldId	`number`	The id of the field where the file is held.

Query Parameters

Parameter Name	Data Type	Description
fileId	`number`	The id of the file to be retrieved.

Retrieve a file from a record in an app

GET /Files/{appId}/{recordId}/{fieldId}

Click to Copy

curl --location 'https://api.onspring.com/v1/Files/195/1/6989?fileId=89' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

Add File

This endpoint allows you to add a file to an image or attachment field on a record in an app.

Path Parameters

Parameter Name	Data Type	Description
appId	`number`	The id of the app or survey where the file is held.
recordId	`number`	The id of the record where the file is held.
fieldId	`number`	The id of the field where the file is held.

Query Parameters

Parameter Name	Data Type	Description
fileName	`string`	The name of the file being added.
modifiedTime	`string`	The modified date and time to be stored with the file. The value should be in this format: `yyyy-mm-dd hh:mm:ssZ`.
fileNotes	`string`	The notes to be stored with the file.

Request Headers

Header	Description
Content-Type	The content type for the file being added.
Content-Length	The number of bytes in the file.

Request Body

The body of the request should include only the bytes that represent the files content.

Response Body Properties

Property Name	Data Type	Description
fileId	`number`	The id of the created file.

Add a file to a record in an app

RESPONSE

Click to Copy

{
  "fileId": 7346
}