API Reference

Form submissions

Submitting a form from code, continuing a submission, and reading what was sent.

Prefix /cdna-api/forms ReferenceFormSubmission model GuideSubmissions
Form submissions in Postman

Submit a form#

POST /cdna-api/forms/submission/{form.id}

Submits a form without a page: the form’s own validation runs, then the submission is stored. It takes no credentials and no CSRF token. Send the values by element name.

The status says what happened:

  • 200: stored and complete; jobs on the submission’s Completed event run.
  • 207: stored but not complete: some answers failed the form’s rules and are kept, marked invalid. The response holds the submission, its token and validationErrors by element name; send every answer again, corrected, with Continue a submission.
  • 422: nothing stored, because the form requires a completed captcha and it was missing or failed. validationErrors lists every problem.
  • 202: a payment is pending. The body holds a redirectUrl to send the visitor to, or a paypalDonateConfig with the submissionToken.

Submitting a form through the API has the whole flow, with the body for each element type.

Access
Anyone. The route takes no credentials, by design.

Parameters

form.idpathrequired
integer
The form id.
element namebody
any
One value per element, by the element’s name. A list takes name[] once per value; a file upload takes the file.

Example

Submit a form 
POST /cdna-api/forms/submission/2 HTTP/1.1
Host: hub.coredna.com
Accept: application/json
Content-Type: multipart/form-data; boundary=----hub

------hub
Content-Disposition: form-data; name="name"

Alex Example
------hub
Content-Disposition: form-data; name="email"

person@example.com
------hub
Content-Disposition: form-data; name="message"

Hello from the API
------hub
Content-Disposition: form-data; name="color[]"

white
------hub
Content-Disposition: form-data; name="color[]"

red
------hub
Content-Disposition: form-data; name="image[]"

@photo.jpg
------hub--
Response 
{
  "result": "success",
  "data": {
    "id": 66,
    "token": "SUBMISSION-TOKEN",
    "stepSubmissions": [
      {
        "elementSubmissions": [
          {
            "name": "name",
            "value": [
              "Alex Example"
            ]
          },
          {
            "name": "email",
            "value": [
              "person@example.com"
            ]
          }
        ]
      }
    ]
  },
  "message": "The Form Submission has been added successfully."
}
{
  "result": "error",
  "validationErrors": {
    "age": [
      {
        "message": "Cannot be empty",
        "code": "bb203946-d5ab-84b9-2afc-41eff2dfe753",
        "propertyPath": "age"
      }
    ]
  },
  "message": "Forms\\Models\\Api\\InputNumber.age: Cannot be empty"
}
Open in Postman docs Saved response from the Postman collection, shortened, with the values replaced

Learn more

GuideSubmitting a form through the API How-toSubmit a Core dna form from a React or Vue front end FAQMy form submission through the API answered 207 FAQOne visitor's form shows up twice among the submissions

Continue a submission#

PUT /cdna-api/forms/submission/{token}

Sends more of an unfinished submission, such as the next step of a multi-step form, addressed by its token. The token is the only credential.

Send every answer again, not only the corrected ones: the whole form is handled again, and an answer left out clears the one stored. 200 returns the submission, complete; 422 lists the errors when the answers are still not valid (never 207, since the submission exists); 202 means a payment is pending. 409 means the submission can no longer change: it is already complete, or an editor published a new revision of the form since it was started; start again with Submit a form.

Access
Anyone. The route takes no credentials, by design.

Parameters

tokenpathrequired
string
The submission’s token, from the response that stored it.
element namebody
any
One value per element, by the element’s name, as for Submit a form.

Example

Continue a submission 
PUT /cdna-api/forms/submission/SUBMISSION-TOKEN HTTP/1.1
Host: hub.coredna.com
Accept: application/json
Content-Type: application/json

{
  "name": "Name from API 335 (edited)",
  "phone": "+1 (23) 456 78 90",
  "color": [
    "red",
    "black"
  ]
}
Response 409 ConflictThe form changed 
{
  "result": "error",
  "message": "The form has been changed and the submission cannot be changed anymore"
}
Open in Postman docs Saved response from the Postman collection, with the message the platform sends now

Learn more

GuideSubmitting a form through the API How-toSubmit a Core dna form from a React or Vue front end FAQMy form submission through the API answered 207

List a form’s submissions#

GET /cdna-api/forms/submissions/{form.id}

Lists the submissions made to one form. Submissions hold what visitors sent, so this needs an admin with access to the form.

Access
Admin users and integrations, with an OAuth access token or an API key.
Model
FormSubmission, in the Reference

Parameters

form.idpathrequired
integer
The form id.
propertiesquery
selector
The fields and relations to return, such as {id,created}.
filtersquery
name=value
Any stored field, or a relation with a dot, such as parent.id=12. Prefix the name with !, >, <, % or |. Use stored field names exactly as in the model, and compare totalCount with the unfiltered list's to confirm a filter applied.
orderByquery
string
field:ASC or field:DESC, comma-separated. Stored fields only.
limitquery
integer
Records per response. There is no default.
offsetquery
integer
Records to skip.

Example

List a form’s submissions 
GET /cdna-api/forms/submissions/11 HTTP/1.1
Host: hub.coredna.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Open in Postman docs

Check a submission’s status#

GET /cdna-api/forms/submission/{token}/status

Says whether a submission is complete. It is how a page waits for a payment provider to confirm a PayPal Donate payment. The 60-character token from the submission is the only credential. Outside the envelope: {"completed": true} or false.

Access
Anyone. The route takes no credentials, by design.

Parameters

tokenpathrequired
string
The submission’s token, 60 characters.

Example

Check a submission’s status 
GET /cdna-api/forms/submission/SUBMISSION-TOKEN/status HTTP/1.1
Host: hub.coredna.com
Accept: application/json
Response 404 Not FoundUnknown token 
{
  "result": "error",
  "message": "Page or record not found"
}
Real response from this documentation site

Learn more

GuideSubmitting a form through the API