cognito-forms — CLI для управления формами Cognito Forms

--- 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://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": "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://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": "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 | 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:support@maton.ai)