# Submit a form

> Submit a form with field values and optional associations with branch, agent, or offer.

Źródło: https://propertly.io/dokumentacja/api/formularze/post-form
Ostatnia aktualizacja: 2026-10-15

`POST https://headless-cms.propertly.io/api/v1/forms/responses`

Submit a form with field values and optional associations with branch, agent, or offer. Supports various field types and can be made idempotent with an idempotency token. To ensure data is properly populated in the lead panel, the following fields should be present: <ol><li> a field of type `PhoneField` with `fieldName` = `'phone_number'`,</li><li> a field of type `EmailField` with `fieldName` = `'email'`,</li><li> a field of type `LocationField` with `fieldName` = `'address'` containing subfields `address_state `, `address_county`, and `address_community`.</li></ol>

Wymaga nagłówka `Authorization: <klucz API>`. Odwołania `$ref` wskazują na `components` w specyfikacji OpenAPI: https://propertly.io/openapi.json

```json
{
  "tags": [
    "Forms"
  ],
  "summary": "Submit a form",
  "description": "Submit a form with field values and optional associations with branch, agent, or offer. Supports various field types and can be made idempotent with an idempotency token. To ensure data is properly populated in the lead panel, the following fields should be present: <ol><li> a field of type `PhoneField` with `fieldName` = `'phone_number'`,</li><li> a field of type `EmailField` with `fieldName` = `'email'`,</li><li> a field of type `LocationField` with `fieldName` = `'address'` containing subfields `address_state `, `address_county`, and `address_community`.</li></ol>",
  "operationId": "post_form_api_v1_forms_responses_post",
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/FormSubmissionRequestDto"
        }
      }
    },
    "required": true
  },
  "responses": {
    "201": {
      "description": "Form successfully submitted",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/FormSubmissionResponseDto"
          },
          "example": {
            "form_response_id": "123e4567-e89b-12d3-a456-426614174000",
            "created": true,
            "created_at": "2025-08-18T11:45:30.000Z"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized",
      "content": {
        "application/json": {
          "examples": {
            "MissingKey": {
              "summary": "No key provided",
              "value": {
                "detail": "API key is required"
              }
            },
            "InvalidKey": {
              "summary": "Invalid key",
              "value": {
                "detail": "Invalid API key"
              }
            },
            "InactiveKey": {
              "summary": "Inactive key",
              "value": {
                "detail": "API key is not active"
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - Invalid branch, agent, or offer association",
      "content": {
        "application/json": {
          "examples": {
            "InvalidBranch": {
              "summary": "Invalid branch",
              "value": {
                "detail": "Branch not found or access not allowed"
              }
            },
            "InvalidAgent": {
              "summary": "Invalid agent",
              "value": {
                "detail": "Agent not found or access not allowed"
              }
            },
            "InvalidOffer": {
              "summary": "Invalid offer",
              "value": {
                "detail": "Offer not found or access not allowed"
              }
            }
          }
        }
      }
    },
    "422": {
      "description": "Validation Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/HTTPValidationError"
          }
        }
      }
    }
  },
  "security": [
    {
      "APIKeyHeader": []
    }
  ]
}
```