Introduction
# Cognito Forms
Access the Cognito Forms API with managed OAuth authentication. List forms, manage entries (create, read, update, delete), and retrieve documents.
## Quick Start
```bash # 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`:
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### Getting Your API Key
1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key
## Connection Management
Manage your Cognito Forms OAuth connections at `https://ctrl.maton.ai`.
### List Connections
```bash 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
```bash 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
```bash 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:** ```json { "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
```bash 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:
```bash 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
```bash GET /cognito-forms/api/forms ```
Returns all forms in the organization.
### Entries
#### Get Entry
```bash GET /cognito-forms/api/forms/{formId}/entries/{entryId} ```
Returns a specific entry by ID or entry number.
#### Create Entry
```bash POST /cognito-forms/api/forms/{formId}/entries Content-Type: application/json
{ "Name": { "First": "John", "Last": "Doe" }, "Email": "[email protected]", "Phone": "555-1234" } ```
Field names match your form's field names. Complex fields like Name and Address use nested objects.
#### Update Entry
```bash PATCH /cognito-forms/api/forms/{formId}/entries/{entryId} Content-Type: application/json
{ "Name": { "First": "Jane", "Last": "Doe" }, "Email": "[email protected]" } ```
Updates an existing entry. Uses PATCH method (not PUT). Fails if the entry includes a paid order.
#### Delete Entry
```bash DELETE /cognito-forms/api/forms/{formId}/entries/{entryId} ```
Deletes an entry. Requires Read/Write/Delete API scope.
### Documents
#### Get Document
```bash GET /cognito-forms/api/forms/{formId}/entries/{entryId}/documents/{templateNumber} ```
Generates and returns a document from an entry using the specified template number.
**Response:** ```json { "Id": "abc123", "Name": "Entry-Document.pdf", "ContentType": "application/pdf", "Size": 12345, "File": "https://temporary-download-url..." } ```
### Files
#### Get File
```bash GET /cognito-forms/api/files/{fileId} ```
Retrieves a file uploaded to a form entry.
**Response:** ```json { "Id": "file-id", "Name": "upload.pdf", "ContentType": "application/pdf", "Size": 54321, "File": "https://temporary-download-url..." } ```
## Field Format Examples
### Name Fields
```json { "Name": { "First": "John", "Last": "Doe" } } ```
### Address Fields
```json { "Address": { "Line1": "123 Main St", "Line2": "Suite 100", "City": "San Francisco", "State": "CA", "PostalCode": "94105" } } ```
### Choice Fields
Single choice: ```json { "PreferredContact": "Email" } ```
Multiple choice: ```json { "Interests": ["Sports", "Music", "Travel"] } ```
## Code Examples
### JavaScript
```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
```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)
```python import os import requests
entry_data = { "Name": {"First": "John", "Last": "Doe"}, "Email": "[email protected]", "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
| Status | Meaning | |--------|---------| | 400 | Missing Cognito Forms connection | | 401 | Invalid or missing Maton API key | | 404 | Form or entry not found | | 429 | Rate limited (100 requests per 60 seconds) | | 4xx/5xx | Passthrough error from Cognito Forms API |
### Troubleshooting: API Key Issues
1. Check that the `MATON_API_KEY` environment variable is set:
```bash echo $MATON_API_KEY ```
2. Verify the API key is valid by listing connections:
```bash 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](https://www.cognitoforms.com/support/475/data-integration/cognito-forms-api) - [REST API Reference](https://www.cognitoforms.com/support/476/data-integration/cognito-forms-api/rest-api-reference) - [API Reference](https://www.cognitoforms.com/support/476/data-integration/cognito-forms-api/api-reference) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])