Cognito Forms API integration with managed OAuth. Access forms, entries, and documents. Use this skill when users want to create, read, update, or delete for...
SKILL.md

---
name: cognito-forms
description: |
  Cognito Forms API integration with managed OAuth. Access forms, entries, and documents.
  Use this skill when users want to create, read, update, or delete form entries, or retrieve form submissions.
  For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
  author: maton
  version: "1.0"
  clawdbot:
    emoji: 🧠
    requires:
      env:
        - MATON_API_KEY
---

# 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://api.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://api.maton.ai/cognito-forms/{native-api-path}
```

Maton 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://api.maton.ai`.

### List Connections

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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://api.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://api.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": "{connection_id}",
    "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://api.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://api.maton.ai/cognito-forms/api/forms')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '{connection_id}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

If you have multiple connections, always include this header to ensure requests go to the intended account.

## Security & Permissions

- Access is scoped to forms, entries, and documents within the connected Cognito Forms account.
- **All write operations require explicit user approval.** Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.

## 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": "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

```bash
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

```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://api.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://api.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": "john@example.com",
    "Message": "Hello from the API!"
}

response = requests.post(
    'https://api.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://api.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://api.maton.ai/cognito-forms/api/forms`
- Incorrect: `https://api.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:support@maton.ai)
Cognito Forms

SKILL.md

related skills
