Cognito Forms

Cognito Forms

Access the Cognito Forms API with managed OAuth authentication. List forms, manage entries (create, read, update, delete), and retrieve documents.

Quick Start

# List all forms
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/cognito-forms/api/forms')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/cognito-forms/{native-api-path}

Replace {native-api-path} with the actual Cognito Forms API endpoint path (starting with api/). The gateway proxies requests to www.cognitoforms.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Cognito Forms OAuth connections at https://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=cognito-forms&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'cognito-forms'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "77de1a60-5f69-45fc-977c-9dfffe7a64d4",
    "status": "ACTIVE",
    "creation_time": "2026-02-08T10:39:10.245446Z",
    "last_updated_time": "2026-02-09T04:11:08.342101Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "cognito-forms",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Cognito Forms connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/cognito-forms/api/forms')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '77de1a60-5f69-45fc-977c-9dfffe7a64d4')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Forms

List Forms

GET /cognito-forms/api/forms

Returns all forms in the organization.

Entries

Get Entry

GET /cognito-forms/api/forms/{formId}/entries/{entryId}

Returns a specific entry by ID or entry number.

Create Entry

POST /cognito-forms/api/forms/{formId}/entries
Content-Type: application/json

{
  "Name": {
    "First": "John",
    "Last": "Doe"
  },
  "Email": "john.doe@example.com",
  "Phone": "555-1234"
}

Field names match your form's field names. Complex fields like Name and Address use nested objects.

Update Entry

PATCH /cognito-forms/api/forms/{formId}/entries/{entryId}
Content-Type: application/json

{
  "Name": {
    "First": "Jane",
    "Last": "Doe"
  },
  "Email": "jane.doe@example.com"
}

Updates an existing entry. Uses PATCH method (not PUT). Fails if the entry includes a paid order.

Delete Entry

DELETE /cognito-forms/api/forms/{formId}/entries/{entryId}

Deletes an entry. Requires Read/Write/Delete API scope.

Documents

Get Document

GET /cognito-forms/api/forms/{formId}/entries/{entryId}/documents/{templateNumber}

Generates and returns a document from an entry using the specified template number.

Response:

{
  "Id": "abc123",
  "Name": "Entry-Document.pdf",
  "ContentType": "application/pdf",
  "Size": 12345,
  "File": "https://temporary-download-url..."
}

Files

Get File

GET /cognito-forms/api/files/{fileId}

Retrieves a file uploaded to a form entry.

Response:

{
  "Id": "file-id",
  "Name": "upload.pdf",
  "ContentType": "application/pdf",
  "Size": 54321,
  "File": "https://temporary-download-url..."
}

Field Format Examples

Name Fields

{
  "Name": {
    "First": "John",
    "Last": "Doe"
  }
}

Address Fields

{
  "Address": {
    "Line1": "123 Main St",
    "Line2": "Suite 100",
    "City": "San Francisco",
    "State": "CA",
    "PostalCode": "94105"
  }
}

Choice Fields

Single choice:

{
  "PreferredContact": "Email"
}

Multiple choice:

{
  "Interests": ["Sports", "Music", "Travel"]
}

Code Examples

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/cognito-forms/api/forms',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const forms = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/cognito-forms/api/forms',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
forms = response.json()

Create Entry Example (Python)

import os
import requests

entry_data = {
    "Name": {"First": "John", "Last": "Doe"},
    "Email": "john@example.com",
    "Message": "Hello from the API!"
}

response = requests.post(
    'https://gateway.maton.ai/cognito-forms/api/forms/ContactForm/entries',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json=entry_data
)

Notes

• List Entries: The Cognito Forms API does not support bulk listing of all entries. Use webhooks or OData for syncing entries.
• Get Form: Returns 404 - use List Forms to get form information instead.
• Form Availability: This endpoint may not be available depending on your Cognito Forms plan.
• Entry IDs can be either the entry number or entry ID (format: {formId}-{entryNumber})
• Complex fields (Name, Address) use nested JSON objects
• File uploads return temporary download URLs
• Document generation creates PDFs from form templates
• API scopes control access: Read, Read/Write, or Read/Write/Delete
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with cognito-forms. For example:

• Correct: https://gateway.maton.ai/cognito-forms/api/forms
• Incorrect: https://gateway.maton.ai/api/forms

Resources

• Cognito Forms API Overview
• REST API Reference
• API Reference
• Maton Community
• Maton Support