Forms API

Create, update, list, and delete forms programmatically.

List Forms

Example Request:

curl https://veilforms.com/api/forms \
  -H "Authorization: Bearer vf_live_xxx"

Response:

{
  "forms": [
    {
      "id": "vf-abc123",
      "name": "Contact Form",
      "createdAt": 1699920000000,
      "submissionCount": 142,
      "publicKey": {
        "kty": "RSA",
        "n": "0vx7agoebG...",
        "e": "AQAB"
      },
      "settings": {
        "encryption": true,
        "piiStrip": true
      }
    },
    {
      "id": "vf-def456",
      "name": "Feedback Form",
      "createdAt": 1699920100000,
      "submissionCount": 58,
      "publicKey": {...},
      "settings": {...}
    }
  ],
  "total": 2
}

Get Form

Example Request:

curl https://veilforms.com/api/forms/vf-abc123 \
  -H "Authorization: Bearer vf_live_xxx"

Response:

{
  "form": {
    "id": "vf-abc123",
    "name": "Contact Form",
    "createdAt": 1699920000000,
    "updatedAt": 1699930000000,
    "submissionCount": 142,
    "publicKey": {
      "kty": "RSA",
      "n": "0vx7agoebG...",
      "e": "AQAB"
    },
    "settings": {
      "encryption": true,
      "piiStrip": true,
      "webhookUrl": "https://yoursite.com/webhook",
      "allowedOrigins": ["https://yoursite.com"]
    },
    "embedCode": "<script src=\"https://veilforms.com/js/veilforms.min.js\"></script>\n<script>VeilForms.init('vf-abc123', {...});</script>"
  }
}

Create Form

Request Body:

{
  "name": "Contact Form",
  "settings": {
    "encryption": true,
    "piiStrip": true,
    "webhookUrl": "https://yoursite.com/webhook",
    "allowedOrigins": ["https://yoursite.com"]
  }
}

Parameters:

FieldTypeRequiredDescription
namestringYesDisplay name for the form
settings.encryptionbooleanNoEnable encryption (default: true)
settings.piiStripbooleanNoStrip PII (default: false)
settings.webhookUrlstringNoURL to receive webhook notifications
settings.allowedOriginsarrayNoCORS origins (default: ["*"])

Example Request:

curl -X POST https://veilforms.com/api/forms \
  -H "Authorization: Bearer vf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Form",
    "settings": {
      "encryption": true,
      "piiStrip": true
    }
  }'

Response:

{
  "form": {
    "id": "vf-abc123",
    "name": "Contact Form",
    "createdAt": 1699920000000,
    "publicKey": {
      "kty": "RSA",
      "n": "0vx7agoebG...",
      "e": "AQAB"
    },
    "privateKey": {
      "kty": "RSA",
      "n": "0vx7agoebG...",
      "e": "AQAB",
      "d": "X4cTteJY_g...",
      "p": "83i-7IvMGX...",
      "q": "3dfOR9cuY..."
    },
    "settings": {
      "encryption": true,
      "piiStrip": true
    }
  }
}

Update Form

Request Body:

{
  "name": "Updated Contact Form",
  "settings": {
    "piiStrip": true,
    "webhookUrl": "https://newsite.com/webhook"
  }
}

Example Request:

curl -X PATCH https://veilforms.com/api/forms/vf-abc123 \
  -H "Authorization: Bearer vf_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Contact Form",
    "settings": {
      "webhookUrl": "https://newsite.com/webhook"
    }
  }'

Response:

{
  "form": {
    "id": "vf-abc123",
    "name": "Updated Contact Form",
    "updatedAt": 1699930000000,
    "settings": {
      "encryption": true,
      "piiStrip": true,
      "webhookUrl": "https://newsite.com/webhook"
    }
  }
}

Delete Form

Query Parameters:

ParameterTypeRequiredDescription
confirmstringYesMust be DELETE_FORM

Example Request:

curl -X DELETE "https://veilforms.com/api/forms/vf-abc123?confirm=DELETE_FORM" \
  -H "Authorization: Bearer vf_live_xxx"

Response:

{
  "success": true,
  "deleted": {
    "formId": "vf-abc123",
    "submissionsDeleted": 142
  }
}

Rotate Keys

Example Request:

curl -X POST https://veilforms.com/api/forms/vf-abc123/rotate-keys \
  -H "Authorization: Bearer vf_live_xxx"

Response:

{
  "form": {
    "id": "vf-abc123",
    "publicKey": {
      "kty": "RSA",
      "n": "NEW_KEY...",
      "e": "AQAB"
    },
    "privateKey": {
      "kty": "RSA",
      "n": "NEW_KEY...",
      "e": "AQAB",
      "d": "NEW_PRIVATE...",
      "p": "...",
      "q": "..."
    },
    "keyVersion": 2,
    "previousKeyVersion": 1,
    "rotatedAt": 1699940000000
  }
}

Form Statistics

Query Parameters:

ParameterTypeRequiredDescription
periodstringNoday, week, month, year (default: month)

Example Request:

curl "https://veilforms.com/api/forms/vf-abc123/stats?period=week" \
  -H "Authorization: Bearer vf_live_xxx"

Response:

{
  "formId": "vf-abc123",
  "period": "week",
  "stats": {
    "totalSubmissions": 142,
    "periodSubmissions": 23,
    "avgPerDay": 3.3,
    "timeline": [
      { "date": "2024-01-01", "count": 5 },
      { "date": "2024-01-02", "count": 3 },
      { "date": "2024-01-03", "count": 4 },
      { "date": "2024-01-04", "count": 2 },
      { "date": "2024-01-05", "count": 6 },
      { "date": "2024-01-06", "count": 1 },
      { "date": "2024-01-07", "count": 2 }
    ]
  }
}

Error Responses

404 Not Found

{
  "error": "not_found",
  "message": "Form not found"
}

400 Bad Request

{
  "error": "bad_request",
  "message": "Invalid form settings",
  "details": {
    "webhookUrl": "Must be a valid HTTPS URL"
  }
}

409 Conflict

{
  "error": "conflict",
  "message": "A form with this name already exists"
}

SDK Integration

After creating a form via API, integrate with the SDK:

// Response from POST /api/forms
const { form } = response;

// Store private key securely (your server/secrets manager)
saveToSecretsManager(form.id, form.privateKey);

// Generate embed code for client
const embedCode = `
<script src="https://veilforms.com/js/veilforms.min.js"></script>
<script>
  VeilForms.init('${form.id}', {
    publicKey: ${JSON.stringify(form.publicKey)},
    encryption: true
  });
</script>
`;

Next Steps