Add applicants via API

6 min

This article shows how to programmatically add applicants to a program via an API. While not part of Roster's published API documentation, there are public endpoints that brands can use to introspect a form's fields and submit applicant information. Applicants submitted via this API appear in the Applicants list, just like those who submitted applications through the form interface.

Overview

Automating applicant submission can be useful for:

Importing applicants from other systems.

Creating integrations with your existing tools.

Batch processing applications.

Streamlining high-volume recruitment workflows.

Important notes

Application forms in Roster are program-specific and identified by a unique form key.

If a team member modifies a program's form for which you're submitting applications via API, you'll need to re-inspect the form structure (Step 1) to adapt your API calls accordingly.

The API credentials used in this guide are not account-specific and provide anonymous access to these publicly-safe endpoints.

Step-by-step instructions

Discover form fields in the application form

Use this endpoint to introspect which fields appear on the form, including validation rules and input options.

Request:

curl 'https://app.getroster.com/v1/api/application-form?key={{form-key}}' \
  -H 'authorization: clientKey e6Ys9wezVp7OQfcuQAjQjES4YAYs3Q| clientSecret Uqa9FQpmERXUVy23ZOlEIg26xLQK3o' \
  -H 'origin: https://apply.getroster.com' \

Replace {{form-key}} with the program's form key, found by copying the form's URL within program settings. Example: https://apply.getroster.com/0NAbZpoap - the form key would be 0NAbZpoap.

Response:

The response contains two important sections:

result.campaign.settings - Indicates which standard form fields are enabled, along with their input options and validation rules

result.properties - Lists all custom properties included in the form, along with input options for checkboxes, radios, and dropdowns, plus validation rules

Example (partial) response:

{
    "success": true,
    "message": null,
    "result": {
        "user": {
            "businessName": "Belle Nutrition"
        },
        "campaign": {
            "id": 1080,
            "settings": {
                "isDefault": true,
                "profileInfo": {
                    "isRequired": true,
                    "isEnabled": true,
                    "isSelected": true
                },
                "questions": {
                    "isEnabled": true
                },
                "shippingInfo": {
                    "isRequired": false,
                    "isEnabled": false
                },
                "fullShippingInfo": {
                    "isRequired": false,
                    "isEnabled": false,
                    "isSelected": false
                },
                "socialInfo": {
                    "isRequired": true,
                    "isEnabled": true,
                    "socialsDetails": {
                        "10": {
                            "isRequired": true,
                            "isEnabled": true
                        }
                    }
                },
                "birthday": {},
                "phoneNumber": {},
                "confirmationMessage": {
                    "title": "Your application has been submitted",
                    "message": "<div>We will review your information as soon as possible. If approved, you will receive an email from us with next steps. <br/><br/>You can safely close this tab.</div>"
                },
                "isDisabled": false,
                "isV2": true
            },
            "campaignFormUrl": "GDZez1sma",
            "eligibleForReward": 0
        },
        "translationApiKey": null,
        "properties": [
            {
                "id": 758,
                "userCampaignId": 1080,
                "sequence": 1,
                "createDate": "2025-03-20T13:02:14.907Z",
                "property": {
                    "id": 446,
                    "userId": 0,
                    "typeId": 296,
                    "label": "Have you purchased from Belle Nutrition before?",
                    "internalLabel": null,
                    "settings": [
                        {
                            "label": "Yes",
                            "value": "Yes"
                        },
                        {
                            "label": "No",
                            "value": "No"
                        }
                    ],
                    "validations": null,
                    "createDate": "2025-03-20T13:02:14.527Z",
                    "active": false,
                    "groupTypeId": null,
                    "searchable": false,
                    "sequence": 0,
                    "profileVisible": false,
                    "fieldType": 0,
                    "groupTypes": null,
                    "systemTypeId": 0,
                    "responseExists": false,
                    "isDefaultProp": false
                }
            },
            {
                "id": 759,
                "userCampaignId": 1080,
                "sequence": 2,
                "createDate": "2025-03-20T13:02:14.907Z",
                "property": {
                    "id": 447,
                    "userId": 0,
                    "typeId": 277,
                    "label": "Tell us why you love Belle Nutrition?",
                    "internalLabel": null,
                    "settings": null,
                    "validations": null,
                    "createDate": "2025-03-20T13:02:14.707Z",
                    "active": false,
                    "groupTypeId": null,
                    "searchable": false,
                    "sequence": 0,
                    "profileVisible": false,
                    "fieldType": 0,
                    "groupTypes": null,
                    "systemTypeId": 0,
                    "responseExists": false,
                    "isDefaultProp": false
                }
            }
        ],
        "supportedNetworks": [
            {
                "typeId": 10,
                "descr": "Instagram",
                "handle": null,
                "totalFollowers": 0,
                "prefix": "https://instagram.com/"
            },
            {
                "typeId": 9,
                "descr": "Twitter",
                "handle": null,
                "totalFollowers": 0,
                "prefix": "https://x.com/"
            },
            {
                "typeId": 20,
                "descr": "YouTube",
                "handle": null,
                "totalFollowers": 0,
                "prefix": "https://youtube.com/"
            }
        ]
    },
    "udfValues": null,
    "errorCode": 0,
    "errorLevel": 0,
    "errorType": 0
}

Get the valid country field options (optional)

Use this endpoint to get the list of valid countries IDs for the country field, if enabled for the form.

Request:

curl 'https://app.getroster.com/v1/api/common/countries' \
  -H 'authorization: clientKey e6Ys9wezVp7OQfcuQAjQjES4YAYs3Q| clientSecret Uqa9FQpmERXUVy23ZOlEIg26xLQK3o' \
  -H 'origin: https://apply.getroster.com' \

Submit an application via API

Use this endpoint to submit an application form via POST request.

Request:

curl 'https://app.getroster.com/v1/api/application-form' \
  --H 'authorization: clientKey e6Ys9wezVp7OQfcuQAjQjES4YAYs3Q | clientSecret Uqa9FQpmERXUVy23ZOlEIg26xLQK3o' \
  --H 'origin: https://apply.getroster.com' \
  --H 'Content-Type: application/json' \
  --data-raw '{
    "key": "{{form-key}}",
    "account": {
        "firstName": "Jane",
        "lastName": "Doe",
        "email": "[email protected]",
        "networks": [
            {
                "typeId": 10,
                "handle": "janedoe"
            }
        ]
    },
    "properties": [
        {
            "userCampaignPropertyId": "16",
            "value": "Running"
        },
        {
            "userCampaignPropertyId": "8",
            "value":"Yes"
        }
    ],
    "formUrl": {
        "url": "https://apply.getroster.com/{{form-key}}",
        "urlParams": {}
    }
}'

Remember to replace both {{form-key}} placeholders with your program's actual form key.

Key components:

authorization: Required header with key/secret (these credentials are not account-specific)

account object: Contains inputs for standard form fields enabled on the form

properties array: Contains inputs for custom properties added to the form

formUrl: The public URL of the form and any URL parameters

Successful response:

{
    "success": true,
    "message": null,
    "errorCode": 0,
    "errorLevel": 0,
    "errorType": 0
}

Troubleshooting

Common issues:

Invalid form key: Ensure you're using the correct form key from the program settings

Missing required fields: Check Step 1 response to confirm all required fields are included in your submission

Invalid field values: For fields with specific options (like dropdowns), ensure you're using exact values from the form structure

Rate limiting: If making many requests, you may encounter rate limits - implement appropriate backoff strategies

Further assistance

For additional help with the Roster API or any issues with applicant submission, please contact Roster support.