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 implements version 3 of the Open API Specification (OAS).

The Onspring API does support bulk operation for some, but not all endpoints. Bulk operations are not supported for endpoints that create, update, or delete resources. The one exception is the batch delete endpoint for records, which is used to delete multiple records at once.

You can specify the version of the API that you want to use by including the version number in the X-Api-Version header. If you do not specify a version number the API will attempt to route the request to the proper version based upon the request path.

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 will be based on the API key provided in the request.

BASE URL

Click to Copy

https://api.onspring.com

X-API-VERSION

Click to Copy

X-Api-Version: 2

Client SDKs

Official

Javascript

Community

Python

Community

dotnet add package Onspring.API.SDK

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": "Date",
  "fieldId": 4800,
  "value": "2023-02-15T06:00:00Z"
}

VALUE FOR DATE FIELD

Click to Copy

{
  "4880": "2023-02-15T06: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": 2, // Internal Record Id
  "fieldData": [
    {
      "type": "Integer",
      "fieldId": 4745,
      "value": 3 // External Record Id
    }
  ]
}

REPORT

Click to Copy

{
  "columns": ["Record Id"],
  "rows": [
    {
      "recordId": 2, // Internal Record Id
      "cells": [
        3 // External Record Id
      ]
    }
  ]
}

Relationships

Reference fields in Onspring are used to relate records to one another whether they be in the same app or in different apps. They can be used to create a one-to-one relationship, a one-to-many relationship, or a many-to-many relationship. This functionality is at the core of how people build and utilize the Onspring platform.

That being said it is likely that when you are working with data in Onspring you will need to work with data that crosses apps. For example you can have a Groups app that has a list of all the groups in your instance and then you can have a Users app that has a list of all the users in your instance. Many users can be related to a single group using a reference field. Therefore if you wanted to collect data for all the users in a group you could make use of the Onspring API to programmatically resolve the relationships between a group record and its related user records and then retrieve the data for each of those users.

You would need to first retrieve the group record which will contain the reference field value that holds all the references to the users in that group. Note the values in a reference field will be the internal Record Id value for each of the related records. You would then need to confirm which app the reference field is targeting and then retrieve the user data for each of the users in the group using the user's Record Id and the Users app id.

Resolving relationships between records

GET GROUP RECORD

Click to Copy

curl --location 'https://api.onspring.com/Records/appId/3/recordId/3' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

GROUP

Click to Copy

{
  "appId": 3,
  "recordId": 3,
  "fieldData": [
    {
      "type": "IntegerList",
      "fieldId": 21, // Users multi select reference field
      "value": [2216]
    }
  ]
}

GET USERS REFERENCE FIELD

Click to Copy

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

REFERENCE FIELD

Click to Copy

{
  "multiplicity": "MultiSelect",
  "referencedAppId": 2, // Users app id
  "id": 21,
  "appId": 3,
  "name": "Users",
  "type": "Reference",
  "status": "Enabled",
  "isRequired": false,
  "isUnique": false
}

GET USER RECORD

Click to Copy

curl --location 'https://api.onspring.com/Records/appId/2/recordId/2216' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

USER

Click to Copy

{
  "appId": 2,
  "recordId": 2216,
  "fieldData": [
    {
      "type": "String",
      "fieldId": 36,
      "value": "TestUser"
    },
    {
      "type": "String",
      "fieldId": 33,
      "value": "stevan.freeborn@onspring.com"
    }
  ]
}

Pagination

The Onspring API supports pagination for some endpoints for some resources. Pagination is used to limit the number of objects returned in a single response. This is useful for reducing the amount of data transferred over the network and for reducing the amount of data that needs to be processed by the client. If you are attempting to retrieve a large number of objects via one of the following endpoints you will need to use pagination to retrieve all of the them. The following endpoints support pagination:

Get Fields by App
Get Records by App
Get Records by Query
Get Reports by App

Pagination Query Parameters

When making a request to one of the endpoints that support pagination you can use the following parameters to control the pagination behavior:

Parameter Name	Data Type	Description
PageNumber	`number`	The page number to retrieve. The default value is `1`.
PageSize	`number`	The number of objects to retrieve per page. The default value is `50`. The maximum value is `1000`.

Pagination Response

When making a request to one of the endpoints that support pagination you will receive a response that contains a Paged Collection object that has the following properties which can be used to determine if there are more pages of data available and to retrieve the next page of data:

Property Name	Data Type	Description
pageNumber	`number`	The page number of the current page of data.
pageSize	`number`	The number of objects per page.
totalPages	`number`	The total number of pages of data available.
totalRecords	`number`	The total number of objects available.
items	`object[]`	The array of objects for the current page.

The Paged Collection Object

PAGED COLLECTION

Click to Copy

{
  "pageNumber": 1,
  "pageSize": 1,
  "totalPages": 1,
  "totalRecords": 1,
  "items": [
    {
      ...,
    }
  ]
}

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 200 response will be returned with no body.

Checking for connection to the api

GET /Ping

Click to Copy

curl --location 'https://api.onspring.com/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 or a specific app by its Id.

App Properties

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

The App Object

APP

Click to Copy

{
  "href": "https://api.onspring.dev/apps/id/195",
  "id": 195,
  "name": "Tasks"
}

Get Apps

This endpoint returns a paged collection of apps that the given API key can access.

Query Parameters

Note: Pagination query parameters can be used to control the number of apps returned in the response.

Retrieve apps accessible to the API key

GET /Apps

Click to Copy

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

RESPONSE

Click to Copy

{
  "pageSize": 1,
  "pageNumber": 1,
  "totalPages": 1,
  "totalRecords": 1,
  "items": [
    {
      "id": 195,
      "name": "Tasks",
      "href": "https://api.onspring.com/Apps/195"
    }
  ]
}

Get App by Id

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

Path Parameters

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

Retrieving an app by its id

GET /Apps/id/{appId}

Click to Copy

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

RESPONSE

Click to Copy

{
  "id": 195,
  "name": "Tasks",
  "href": "https://api.onspring.com/Apps/195"
}

Get Apps by Ids

This endpoint returns a batch of apps based on the given app ids. The max number of apps that can be requested is 100.

Request Body

REQUEST

Click to Copy

[8, 79, 137, 193, 183]

Response Body Properties

Property Name	Data Type	Description
count	`number`	The number of apps returned.
items	`object[]`	The apps returned.

Retrieve a batch of apps by ids

POST /Apps/batch-get

Click to Copy

curl --location 'https://api.onspring.com/Apps/batch-get' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
--header 'Content-Type: application/json' \
--data '[8,79,137,193,183]'

RESPONSE

Click to Copy

{
  "count": 5,
  "items": [
    {
      "href": "https://api.onspring.dev/apps/id/8",
      "id": 8,
      "name": "Activated BCDR Tasks"
    },
    {
      "href": "https://api.onspring.dev/apps/id/79",
      "id": 79,
      "name": "Application Assessments"
    },
    {
      "href": "https://api.onspring.dev/apps/id/137",
      "id": 137,
      "name": "Applications"
    },
    {
      "href": "https://api.onspring.dev/apps/id/193",
      "id": 193,
      "name": "Ascent Obligations"
    },
    {
      "href": "https://api.onspring.dev/apps/id/183",
      "id": 183,
      "name": "Asset Baseline Repository"
    }
  ]
}

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[]`	An array of Report Row objects.

The Report Data Object

REPORT DATA

Click to Copy

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

Report Row

These are objects representing a row in a report. They will comprise the rows array in the Report Data object. Each row contains the data for a record in the report.

Report Row Properties

Property Name	Data Type	Description
recordId	`number`	The id of the record that the row represents.
cells	`string[]`	An array of strings representing the data for each field in the report. The order of the strings in the array will match the order of the fields in the `columns` array in the Report Data object.

The Report Row Object

REPORT ROW

Click to Copy

{
  "recordId": 72,
  "cells": [
    "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 a paged collection of reports for the given app.

Query Parameters

Note: Pagination query parameters can be used to control the number of reports returned in the response.

Retrieving reports for the given app

GET /Reports/appId/{appId}

Click to Copy

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

RESPONSE

Click to Copy

{
  "pageNumber": 1,
  "pageSize": 1,
  "totalPages": 1,
  "totalRecords": 1,
  "items": [
    {
      "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
apiDataFormat	`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/id/613' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

RESPONSE

Click to Copy

{
  "columns": [
    "Name",
    "Owner",
    "Due Date",
    "Status",
    "Description"
  ],
  "rows": [
    {
      "recordId": 72,
      "cells": [
        "A New Test Task",
        null,
        null,
        null,
        "<p>This is a test task.</p>"
      ]
    },
    {
      "recordId": 73,
      "cells": [
        "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	`string`	The type of the field. Possible values are: `Attachment`, `AutoNumber`, `Date`, `Formula`, `Image`, `List`, `Number`, `Reference`, `SurveyCampaign`, `SurveyGroupScoring`, `SurveyReference`, `SurveyUnifiedAnswer`,`Text`, or `TimeSpan`.
status	`string`	The status of the field. Possible values are: `Enabled` or `Disabled`.
isRequired	`boolean`	Indicates whether the field is configured to be required.
isUnique	`boolean`	Indicates whether the field is configured to be unique.

The Field Object

FIELD

Click to Copy

{
  "id": 6983,
  "appId": 195,
  "name": "Name",
  "type": "Text",
  "status": "Enabled",
  "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	`string`	Indicates the type of the output of the formula field. Possible values are: `Text`,`Numeric`, `DateAndTime`, or `ListValue`.
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`.

The Formula Field Object

FORMULA FIELD

Click to Copy

{
  "outputType": "ListValue",
  "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": "Formula",
  "status": "Enabled",
  "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 identify the app or survey that the related content records are held in therefore they have the following additional properties in addition to the standard Field properties.

Reference Field Properties

Property Name	Data Type	Description
multiplicity	`string`	Indicates whether the field is single or multi select. Possible values are: `MultiSelect` or `SingleSelect`.
referenceAppId	`number`	The id of the app that the related content records are held in.

The Reference Field Object

REFERENCE FIELD

Click to Copy

{
  "multiplicity": "MultiSelect",
  "referencedAppId": 2,
  "id": 4808,
  "appId": 130,
  "name": "multi_select_reference_field",
  "type": "Reference",
  "status": "Enabled",
  "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	`string`	Indicates whether the field is single or multi select. Possible values are: `MultiSelect` or `SingleSelect`.
listId	`number`	The id of the list that the list values are associated with.
values	`object[]`	An array of List Value objects that define the possible values of the list field.

The List Field Object

LIST FIELD

Click to Copy

{
  "multiplicity": "MultiSelect",
  "listId": 639,
  "values": [
    {
      "id": "71afe161-34f9-49d0-b45e-968b764c884c",
      "name": "list_value_1",
      "sortOrder": 1,
      "numericValue": 1,
      "color": "#008e8e"
    },
    {
      "id": "d40a74dd-abb5-4fbb-82c0-5766e871e2a4",
      "name": "list_value_2",
      "sortOrder": 2,
      "numericValue": 2,
      "color": "#a186be"
    }
  ],
  "id": 4802,
  "appId": 130,
  "name": "multi_select_list_field",
  "type": "List",
  "status": "Enabled",
  "isRequired": false,
  "isUnique": false
}

Get Fields by App

This endpoint returns a paged collection of Fields for the given app.

Path Parameters

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

Query Parameters

Note: Pagination query parameters can be used to control the number of fields returned in the response.

Retrieve all fields for an app

GET /Fields/appId/{appId}

Click to Copy

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

RESPONSE

Click to Copy

{
  "pageNumber": 1,
  "pageSize": 2,
  "totalPages": 1,
  "totalRecords": 2,
  "items": [
    {
      "id": 6989,
      "appId": 195,
      "name": "Attachments",
      "type": "Attachment",
      "status": "Enabled",
      "isRequired": false,
      "isUnique": false
    },
    {
      "multiplicity": "SingleSelect",
      "referencedAppId": 2,
      "id": 6980,
      "appId": 195,
      "name": "Created By",
      "type": "Reference",
      "status": "Enabled",
      "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/id/{fieldId}

Click to Copy

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

RESPONSE

Click to Copy

{
  "multiplicity": "SingleSelect",
  "listId": 906,
  "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": "List",
  "status": "Enabled",
  "isRequired": false,
  "isUnique": false
}

Get Fields by Ids

This endpoint returns a batch of Fields by their ids. The max number of fields that can be requested is 100.

Request Body

REQUEST

Click to Copy

[6983, 6986, 6987, 6985, 6984]

Response Body Properties

Property Name	Data Type	Description
count	`number`	The number of fields returned.
items	`object[]`	The fields returned.

Retrieve a batch of fields by ids

POST /Fields/batch-get

Click to Copy

curl --location 'https://api.onspring.com/Fields/batch-get' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
--header 'Content-Type: application/json' \
--data '[6983,6986,6987,6985,6984]'

RESPONSE

Click to Copy

{
  "count": 1,
  "items": [
    {
      "id": 6983,
      "appId": 195,
      "name": "Name",
      "type": "Text",
      "status": "Enabled",
      "isRequired": false,
      "isUnique": false
    }
  ]
}

List Values

These are objects that represent the defined values of a List Field or a Formula Field with a ListValue 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": "71afe161-34f9-49d0-b45e-968b764c884c",
  "name": "list_value_1",
  "sortOrder": 1,
  "numericValue": 1,
  "color": "#008e8e"
}

Save List Value

This endpoint adds or updates a list value. If a list value id is provided, the list value will be updated. If no list value id is provided, a new list value will be created. When request is successful a 200 status code will be returned if updating a list value or a 201 status code will be returned if creating a new list value.

Path Parameters

Property Name	Data Type	Description
`listId`	`number`	The id of the list to which the list value belongs.

Request Body Properties

Property Name	Data Type	Description
id	`number`	The id of the list value to update. If no id is provided, a new list value will be created.
name	`string`	The name of the list value.
numericValue	`number`	The numeric value of the list value.
color	`string`	The color of the list value.

Response Body Properties

Property Name	Data Type	Description
id	`string`	The id of the list value.

Add a list value

PUT /Lists/id/{listId}/items

Click to Copy

curl --location --request PUT 'https://api.onspring.com/Lists/id/906/items' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
--header 'Content-Type: application/json' \
--data '{
  "id": null,
  "name": "Not Started",
  "numericValue": 0,
  "color": "#ffffff",
}'

RESPONSE

Click to Copy

{
  "id": "4118d53a-9121-4345-8682-07f23d606daa"
}

Delete List Value by Id

This endpoint deletes a list value. When request is successful a 204 status code will be returned with no response body.

Delete a list value

DELETE /Lists/id/{listId}/itemId/{itemId}

Click to Copy

curl --location --request DELETE 'https://api.onspring.com/Lists/id/906/itemId/e3371dbf-b557-4a31-b32f-33c0265d2a59' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

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": 195,
  "recordId": 1,
  "fieldData": [
    {
      "type": "Integer",
      "fieldId": 6976,
      "value": 1
    }
  ]
}

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	`string`	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
String	A string value.	`string`
Integer	An integer value.	`number`
Decimal	A decimal value.	`number`
Date	A date value.	`string`
TimeSpan	A Time Span value.	`object`
Guid	A GUID value.	`string`
StringList	A list of string values.	`string[]`
IntegerList	A list of integer values.	`number[]`
GuidList	A list of GUID values.	`string[]`
AttachmentList	A list of Attachment values.	`object[]`
ScoringGroupList	A list of Scoring Group values.	`object[]`
FileList	A list of file values.	`number[]`

Time Span Field Value

Property Name	Data Type	Description
quantity	`number`	The number of the specified increment.
increment	`string`	The increment of time. Can be one of the following values: `Years`, `Months`, `Weeks`, `Days`, `Hours`, `Minutes`, `Seconds`.
recurrence	`string`	The recurrence of the time span. Can be one of the following values: `None`, `EndByDate`, `EndAfterOccurrences`.
endByDate	`string`	The end date of the time span. This will only be set if `recurrence` is set to `EndByDate`.
endAfterOccurrences	`number`	The number of occurrences of the time span. This will only be set if `recurrence` is set to `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	`string`	The storage location of the file. Can be one of the following values: `Internal`, `OneDrive`, `GoogleDrive`.
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`.

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": "Integer",
  "fieldId": 6976,
  "value": 1
},
{
  "type": "Date",
  "fieldId": 4746,
  "value": "2023-02-16T05:14:14Z"
},
{
  "type": "String",
  "fieldId": 4753,
  "value": "test@test.com"
},
{
  "type": "Decimal",
  "fieldId": 4756,
  "value": 15.3
},
{
  "type": "ScoringGroupList",
  "fieldId": 4762,
  "value": [
    {
      "listValueId": "c9e4d695-184c-48ec-a8ef-01a52b2bce39",
      "name": "scoring_group_list_1",
      "score": 5,
      "maximumScore": 6
    },
  ]
},
{
  "type": "IntegerList",
  "fieldId": 4792,
  "value": [
    1,
    2,
  ]
},
{
  "type": "Guid",
  "fieldId": 4801,
  "value": "2c1af5b1-0f90-4378-b9a5-8b7e22f2bc84"
},
{
  "type": "GuidList",
  "fieldId": 4802,
  "value": [
    "71afe161-34f9-49d0-b45e-968b764c884c",
    "d40a74dd-abb5-4fbb-82c0-5766e871e2a4"
  ]
},
{
  "type": "AttachmentList",
  "fieldId": 4806,
  "value": [
    {
      "fileId": 909,
      "fileName": "test-attachment.txt",
      "notes": "This is a test",
      "storageLocation": "Internal"
    },
  ]
},
{
  "type": "TimeSpan",
  "fieldId": 4811,
  "value": {
    "quantity": 10,
    "increment": "Minutes",
    "recurrence": "None"
  }
},
{
  "type": "StringList",
  "fieldId": 4999,
  "value": [
    "list_value_1",
    "list_value_2"
  ]
},
{
  "type": "FileList",
  "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 specified either in a query parameter or in the request body. These endpoints are:

Get Records by App
Get Record by Id
Get Records by Ids
Get Records by Query

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": 1,
  "fieldData": [
    {
      "type": "Integer",
      "fieldId": 4745, // AutoNumber Field
      "value": 1
    },
    {
      "type": "Date",
      "fieldId": 4800, // Date/Time Field
      "value": "2023-02-15T06:00:00Z"
    },
    {
      "type": "Guid",
      "fieldId": 4833, // Single Select List Field
      "value": "9a08da5e-db5d-447f-9be9-ce8d7d7e61a7"
    },
    {
      "type": "GuidList",
      "fieldId": 4830, // Multi Select List Field
      "value": [
        "624714d7-d22d-414f-ab62-9071d993e796",
        "46f87c6b-be0a-46a2-b7de-e100779e1643"
      ]
    },
    {
      "type": "Decimal",
      "fieldId": 4803, // Number Field
      "value": 100
    },
    {
      "type": "String",
      "fieldId": 4805, // Text Field
      "value": "<p>This is a test</p>"
    },
    {
      "type": "TimeSpan",
      "fieldId": 4810, // TimeSpan Field
      "value": {
        "quantity": 11,
        "increment": "Seconds",
        "recurrence": "EndAfterOccurrences",
        "endAfterOccurrences": 1
      }
    }
  ]
}

The Values in a Formatted Response

RAW

Click to Copy

{
  "appId": 130,
  "recordId": 1,
  "fieldData": [
    {
      "type": "String",
      "fieldId": 4745, // AutoNumber Field
      "value": "recordId-1"
    },
    {
      "type": "String",
      "fieldId": 4800, // Date/Time Field
      "value": "Wednesday, February 15, 2023 6:00 AM"
    },
    {
      "type": "String",
      "fieldId": 4833, // Single Select List Field
      "value": "list_value_1"
    },
    {
      "type": "StringList",
      "fieldId": 4830, // Multi Select List Field
      "value": ["list_value_1", "list_value_2"]
    },
    {
      "type": "String",
      "fieldId": 4803, // Number Field
      "value": "$100 dollars"
    },
    {
      "type": "String",
      "fieldId": 4805, // Text Field
      "value": "This is a test"
    },
    {
      "type": "String",
      "fieldId": 4810, // TimeSpan Field
      "value": "Every 11 Second(s) End After 1 Occurrences"
    }
  ]
}

Get Records by App

This endpoint returns a paged collection 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

Note: Pagination query parameters can be used to control the number of records returned.

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 records for an app

GET /Records/appId/{appId}

Click to Copy

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

RESPONSE

Click to Copy

{
  "pageNumber": 1,
  "pageSize": 1,
  "totalPages": 1,
  "totalRecords": 1,
  "items": [
    {
      "appId": 195,
      "recordId": 1,
      "fieldData": [
        {
          "type": "Integer",
          "fieldId": 6976,
          "value": 1
        }
      ]
    }
  ]
}

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/{appId}/recordId/{recordId}

Click to Copy

curl --location 'https://api.onspring.com/Records/appId/195/recordId/1' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

RESPONSE

Click to Copy

{
  "appId": 195,
  "recordId": 1,
  "fieldData": [
    {
      "type": "Integer",
      "fieldId": 6976,
      "value": 1
    }
  ]
}

Get Records by Ids

This endpoint returns a batch of records that match the given ids. The max number of records that can be requested is 100.

Request Body Properties

Property Name	Data Type	Description
appId	`number`	The id of the app or survey that contains the records.
recordIds	`number[]`	The ids of the records to return.
fieldIds	`number[]`	The ids of the fields to return in the records.
dataFormat	`string`	The format of the field data in the response. Valid values are `Raw` and `Formatted`. If not specified, `Raw` will be used.

Response Body Properties

Property Name	Data Type	Description
count	`number`	The number of records returned.
items	`object[]`	The records returned.

Retrieving a batch of records

POST /Records/batch-get

Click to Copy

curl --location 'https://api.onspring.com/Records/batch-get' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
--header 'Content-Type: application/json' \
--data '{
  "appId": 195,
  "recordIds": [1],
  "fieldIds": [6983,6986,6987,6985,6984],
  "dataFormat": "Raw"
}'

RESPONSE

Click to Copy

{
  "count": 1,
  "items": [
    {
      "appId": 195,
      "recordId": 1,
      "fieldData": [
        {
          "type": "String",
          "fieldId": 6983,
          "value": "Test Task 1"
        },
        {
          "type": "Guid",
          "fieldId": 6986,
          "value": "4118d53a-9121-4345-8682-07f23d606daa"
        },
        {
          "type": "Integer",
          "fieldId": 6987,
          "value": 2
        },
        {
          "type": "Date",
          "fieldId": 6985,
          "value": "2021-12-31T06:00:00Z"
        },
        {
          "type": "String",
          "fieldId": 6984,
          "value": "<p>This is a test!</p>"
        }
      ]
    }
  ]
}

Get Records by Query

This endpoint returns a paged collection of records for a given app or survey.

Query Parameters

Note: Pagination query parameters can be used to control the number of records returned.

Request Body Properties

Property Name	Data Type	Description
appId	`number`	The id of the app or survey that contains the records.
filter	`string`	A filter expression that will be used to filter the records returned.
fieldIds	`number[]`	The ids of the fields to return in the records.
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 by the Get Records by Query endpoint. 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`.
contains	Determines if the field contains a list value. List value can be its id or name.	`List` fields and formulas with output type of `list`.
isnull	Determines if the field is null.	`Text`, `number`, `date`, and `auto-number` fields and formula fields that have an output type of `text`, `number`, or `date`.
notnull	Determines if the field is not null.	`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.

Querying for records in an app

POST /Records/Query

Click to Copy

curl --location 'https://api.onspring.com/Records/Query' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
--header 'Content-Type: application/json' \
--data '{
    "appId": 195,
    "filter": "6983 eq '\''Test Task 5'\''",
    "fieldIds": [6983,6986,6987,6985,6984],
    "dataFormat": "Formatted"
}'

RESPONSE

Click to Copy

{
  "pageNumber": 1,
  "pageSize": 1,
  "totalPages": 1,
  "totalRecords": 1,
  "items": [
    {
      "appId": 195,
      "recordId": 5,
      "fieldData": [
        {
          "type": "String",
          "fieldId": 6983,
          "value": "Test Task 5"
        },
        {
          "type": "String",
          "fieldId": 6986,
          "value": "Complete"
        },
        {
          "type": "Integer",
          "fieldId": 6987,
          "value": 2
        },
        {
          "type": "String",
          "fieldId": 6985,
          "value": "12/31/2021 6:00 AM"
        },
        {
          "type": "String",
          "fieldId": 6984,
          "value": "This is a test!"
        }
      ]
    }
  ]
}

Save Record

This endpoint allows you to add or update a record in an app. If a record id is provided in the request, the record will be updated and a 200 response will be returned. If no record id is provided, a new record will be created and a 201 response will be returned. When successful the response will contain the record id of the record that was created or updated and any warnings that were encountered.

Request Body Properties

Property Name	Data Type	Description
appId	`number`	The id of the app that contains or will contain the record.
recordId	`number`	The id of the record to update. If this property is not provided, a new record will be created.
fields	`object`	An object containing the field values to save. The keys of the object should be the field ids and the values should be the field values. The field values should be in the format that is expected by the field type.

Response Body Properties

Property Name	Data Type	Description
recordId	`number`	The id of the record that was created or updated.
warnings	`string[]`	An array of warnings that were encountered while saving the record.

Add a record to an app

PUT /Records

Click to Copy

curl --location --request PUT 'https://api.onspring.com/Records' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
--header 'Content-Type: application/json' \
--data '{
  "appId": 195,
  "recordId": null,
  "fields": {
    "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

{
  "warnings": [],
  "id": 140
}

Delete Record by Id

This endpoint allows you to delete a record from an app. When successful, a 204 response will be returned with no body.

Path Parameters

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

Deleting a record from an app

DELETE /Records/appId/{appId}/recordId/{recordId}

Click to Copy

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

Delete Records by Ids

This endpoint deletes multiple records by their ids. When successful, a 204 response will be returned with no body.

Request Body Properties

Property Name	Data Type	Description
appId	`number`	The id of the app that contains the records to delete.
recordIds	`number[]`	The ids of the records to delete.

Deleting a batch of records from an app

DELETE Records/batch-delete

Click to Copy

curl --location 'https://api.onspring.com/Records/batch-delete' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
--header 'Content-Type: application/json' \
--data '{
  "appId": 195,
  "recordIds": [138,139]
}'

Files

Files represent the information held in Attachment and Image fields. The Onspring API can be used to retrieve information about a file and the file itself. The Onspring API can also be used to add and remove files to and from Attachment and Image fields.

File Information Properties

Property Name	Data Type	Description
type	`string`	The type of the file. This will be either `Attachment` or `Image`.
contentType	`string`	The MIME type of the file.
name	`string`	The name of the file.
createdDate	`string`	The date and time the file was created.
modifiedDate	`string`	The date and time the file was last modified.
owner	`string`	The id of the user who owns the file.
notes	`string`	The notes associated with the file.
fileHref	`string`	The URL of the file.

The File Information Object

FILE INFORMATION

Click to Copy

{
  "type": "Attachment",
  "contentType": "text/plain",
  "name": "Test Attachment.txt",
  "createdDate": "2021-12-13T21:34:14.519Z",
  "modifiedDate": "2021-12-13T21:34:19.236Z",
  "owner": "e7d20e9e-0bce-40e2-8fdb-f8c839a982cb",
  "notes": "",
  "fileHref": "https://api.onspring.dev/files/record/1/field/6989/file/89/file"
}

Get File Info by Id

This endpoint returns information about the given file.

Path Parameters

Parameter Name	Data Type	Description
recordId	`number`	The id of the record that contains the file.
fieldId	`number`	The id of the field that contains the file.
fileId	`number`	The id of the file.

Retrieve a file's information by it's id

GET /Files/recordId/{recordId}/fieldId/{fieldId}/fileId/{fileId}

Click to Copy

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

RESPONSE

Click to Copy

{
  "type": "Attachment",
  "contentType": "text/plain",
  "name": "Test Attachment.txt",
  "createdDate": "2021-12-13T21:34:14.519Z",
  "modifiedDate": "2021-12-13T21:34:19.236Z",
  "owner": "e7d20e9e-0bce-40e2-8fdb-f8c839a982cb",
  "notes": "",
  "fileHref": "https://api.onspring.dev/files/record/1/field/6989/file/89/file"
}

Get File by Id

This endpoint returns the file with the given id.

Path Parameters

Parameter Name	Data Type	Description
recordId	`number`	The id of the record that contains the file.
fieldId	`number`	The id of the field that contains the file.
fileId	`number`	The id of the file.

Retrieve a file by it's id

GET /Files/recordId/{recordId}/fieldId/{fieldId}/fileId/{fileId}/file

Click to Copy

curl --location 'https://api.onspring.com/Files/recordId/1/fieldId/6989/fileId/89/file' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'

RESPONSE

Click to Copy

this is only a test

Add File

This endpoint allows you to add a file to a record. The request body must be of type multipart/form-data.

Request Body Fields

Property Name	Data Type	Description
recordId	`number`	The id of the record to which the file will be added.
fieldId	`number`	The id of the field to which the file will be added.
notes	`string`	The notes to be added to the file.
modifiedDate	`string`	The date the file was last modified.
file	`binary`	The file to be added.

Response Body Properties

Property Name	Data Type	Description
id	`number`	The id of the file that was added.

Add a file to a record

POST /Files

Click to Copy

curl --location 'https://api.onspring.com/Files' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000' \
--form 'recordId="140"' \
--form 'fieldId="6989"' \
--form 'notes="Updating record with attachment."' \
--form 'modifiedDate=""' \
--form 'file=@"test-attachment.txt"'

RESPONSE

Click to Copy

{
  "id": 1904
}

Delete File by Id

This endpoint deletes the given file. If the request is successful a 204 response will be returned with an empty body.

Path Parameters

Parameter Name	Data Type	Description
recordId	`number`	The id of the record that contains the file.
fieldId	`number`	The id of the field that contains the file.
fileId	`number`	The id of the file.

Deleting a file by it's id

DELETE /Files/recordId/{recordId}/fieldId/{fieldId}/fileId/{fileId}/file

Click to Copy

curl --location --request DELETE 'https://api.onspring.com/Files/recordId/140/fieldId/6989/fileId/1904' \
--header 'X-ApiKey: 000000ffffff000000ffffff/00000000-ffff-0000-ffff-000000000000'