{ "openapi": "3.0.0", "info": { "version": "1.0", "title": "Cognito Forms OData Service", "description": "

The Cognito Forms OData Service allows you to integrate your existing systems with Cognito Forms without third-party tools. The OData service gives you the ability to programmatically interact with your organization's entries.

The Cognito Forms OData Service is available to all organizations on the Pro, Team, and Enterprise plans.

See our guide on Data Analytics Tools to learn more about the Cognito Forms OData Service.

Authentication

The Cognito Forms OData Service uses bearer authentication. Add your access token to the Authorization header, prefaced with Bearer. Alternatively, you can add your access token as a query string parameter (access_token). Access tokens sent as form-encoded parameters are not supported.

", "contact": { "name": "Cognito Forms Support", "email": "support@cognitoforms.com", "url": "https://www.cognitoforms.com/support" } }, "servers": [ { "url": "https://www.cognitoforms.com/api/odata" } ], "security": [ { "Bearer": [] } ], "paths": { "/Forms": { "get": { "tags": [ "Forms" ], "summary": "Get Forms", "description": "Retrieves a list of forms in your organization that are accessible by the specified API key. Archived forms are not included in the response.
Required Scopes - `Form:Read`", "operationId": "GetForms", "parameters": [ { "name": "$count", "in": "query", "description": "Returns the number of Forms in the response", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "An OData JSON payload", "properties": { "@odata.context": { "description": "The URL for the Get Forms metadata document", "type": "string" }, "value": { "type": "array", "items": { "$ref": "#/components/schemas/Form" } } } }, "example": { "@odata.context": "https://cognitoforms.com/api/odata/$metadata#Forms", "value": [ { "@odata.id": "https://cognitoforms.com/api/odata/Forms(1)", "Id": 1, "Name": "My Form", "InternalName": "MyForm" }, { "@odata.id": "https://cognitoforms.com/api/odata/Forms(2)", "Id": 2, "Name": "My Form 2", "InternalName": "My Form 2" } ] } } } }, "401": { "$ref": "#/components/responses/401" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/$metadata#Forms": { "get": { "tags": [ "Forms" ], "summary": "Get Forms Metadata", "description": "Retrieves the metadata document for the Get Forms endpoint. The XML metadata document includes all properties, and their data types.
Required Scopes - `Form:Read`", "operationId": "GetFormsMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "XML metadata schema document a Form", "type": "object" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/Forms({formId})": { "get": { "tags": [ "Forms" ], "summary": "Get Form", "description": "Retrieves details for a specified Form
Required Scopes - `Form:Read`", "operationId": "GetForm", "parameters": [ { "name": "formId", "in": "path", "description": "The ID of the Form for which you want to retrieve details", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "An OData JSON payload", "properties": { "@odata.context": { "description": "The URL for the Get Form metadata document", "type": "string" }, "@odata.id": { "description": "The canonical URL of the Form", "type": "string" }, "Id": { "description": "The unique ID of the Form", "type": "integer" }, "Name": { "description": "The name of the Form", "type": "string" }, "InternalName": { "description": "The unique internal name of the Form", "type": "string" } } }, "example": { "@odata.context": "https://cognitoforms.com/api/odata/$metadata#Forms/$entity", "@odata.id": "https://cognitoforms.com/api/odata/Forms(1)", "Id": 1, "Name": "My Form", "InternalName": "MyForm" } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/$metadata#Forms/$entity": { "get": { "tags": [ "Forms" ], "summary": "Get Form Metadata", "description": "Retrieves the metadata document for the Get Form endpoint. The XML metadata document includes all properties, and their data types.
Required Scopes - `Form:Read`", "operationId": "GetFormMetadata", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "XML metadata schema document a Form", "type": "object" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/Forms({formId})/Views({viewId})/Entries": { "get": { "tags": [ "Entries" ], "summary": "Get Entries in a View", "description": "Retrieves a list of entries and their fields using the specified form ID and view ID. The response only includes entries in grid views.
Required Scopes - `Form:Read` `Entry:Read`", "operationId": "GetEntries", "parameters": [ { "name": "formId", "in": "path", "description": "The ID of the Form for which you want to retrieve Entries", "required": true, "schema": { "type": "integer" } }, { "name": "viewId", "in": "path", "description": "The ID of the View for which you want to retrieve Entries", "required": true, "schema": { "type": "integer" } }, { "name": "$count", "in": "query", "description": "Returns the number of Entries in the response", "required": false, "schema": { "type": "boolean" } }, { "name": "$select", "in": "query", "description": "Returns list of entry IDs in a View when $select=Id is specified", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "An OData JSON payload", "properties": { "@odata.context": { "description": "The URL for the entries metadata document", "type": "string" }, "value": { "type": "array", "items": { "$ref": "#/components/schemas/Entry" } } } }, "example": { "@odata.context": "https://cognitoforms.com/api/odata/Forms(1)/Views(1)/$metadata#Entries", "value": [ { "@odata.id": "https://cognitoforms.com/api/odata/Forms(1)/Views(1)/Entries(1)", "Id": 1, "TextboxField": "Textbox no.1", "NumberField": 3 }, { "@odata.id": "https://cognitoforms.com/api/odata/Forms(1)/Views(1)/Entries(2)", "Id": 2, "TextboxField": "Textbox no.2", "NumberField": 8 } ] } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/Forms({formId})/Views({viewId})/$metadata#Entries": { "get": { "tags": [ "Entries" ], "summary": "Get Entries in a View Metadata", "description": "Retrieves the metadata document for the Get Entries endpoint. The XML metadata document includes all properties, and their data types.
Required Scopes - `Form:Read`", "operationId": "GetEntriesMetadata", "parameters": [ { "name": "formId", "in": "path", "description": "The ID of the Form", "required": true, "schema": { "type": "integer" } }, { "name": "viewId", "in": "path", "description": "The ID of the View", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "Schema for the specified Form and View", "type": "object" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/Forms({formId})/Views({viewId})/Entries({entryId})": { "get": { "tags": [ "Entries" ], "summary": "Get Entry", "description": "Retrieves details for a specified Entry.
Required Scopes - `Entry:Read`", "operationId": "GetEntry", "parameters": [ { "name": "formId", "in": "path", "description": "The ID of the Form for which you want to retrieve an Entry", "required": true, "schema": { "type": "integer" } }, { "name": "viewId", "in": "path", "description": "The ID of the View for which you want to retrieve an Entry", "required": true, "schema": { "type": "integer" } }, { "name": "entryId", "in": "path", "description": "The ID of the Entry you want to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entry" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } }, "/Forms({formId})/Views({viewId})/$metadata#Entries/$entity": { "get": { "tags": [ "Entries" ], "summary": "Get Entry Metadata", "description": "Retrieves the metadata document for the Get Entry endpoint. The XML metadata document includes all properties, and their data types.
Required Scopes - `Form:Read`", "operationId": "GetEntryMetadata", "parameters": [ { "name": "formId", "in": "path", "description": "The ID of the Form", "required": true, "schema": { "type": "integer" } }, { "name": "viewId", "in": "path", "description": "The ID of the View", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "description": "Schema for the specified Form and View", "type": "object" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "404": { "$ref": "#/components/responses/404" }, "429": { "$ref": "#/components/responses/429" }, "500": { "$ref": "#/components/responses/500" } } } } }, "components": { "schemas": { "Form": { "description": "A Form", "type": "object", "properties": { "@odata.id": { "description": "The canonical URL of the Form", "type": "string" }, "Id": { "description": "The Form ID", "type": "integer" }, "Name": { "description": "The name of the Form", "type": "string" }, "InternalName": { "description": "The unique internal name of the Form", "type": "string" } } }, "Entry": { "description": "A Form Entry", "type": "object", "properties": { "@odata.id": { "description": "The canonical URL of the Entry", "type": "string" }, "Id": { "description": "The Entry ID", "type": "integer" } } }, "Error": { "description": "An error", "type": "object", "properties": { "Message": { "description": "A message describing the error", "type": "string" }, "Type": { "description": "The type of the error", "type": "string" }, "SupportCode": { "description": "A support code identifying the specific error", "type": "string" }, "Data": { "description": "Data related to the error", "type": "object" } }, "example": { "Message": "An unknown error occurred.", "Type": "UnknownError", "SupportCode": "ABC-123-DEF", "Data": null } } }, "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "200": { "description": "OK" }, "201": { "description": "Created" }, "204": { "description": "No Content" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too Many Requests", "headers": { "Retry-After": { "description": "The datetime after which you may retry the request", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }