--- title: Add applicants via API slug: add-applicants-via-api description: How to programmatically add applicants to a program via an API. Covers important notes, step-by-step instructions, and more in Roster. docTags: createdAt: 2025-04-09T21:43:57.327Z --- 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 ::::WorkflowBlock :::WorkflowBlockItem ### 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 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: 1. `result.campaign.settings` - Indicates which standard form fields are enabled, along with their input options and validation rules 2. `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: ```javascript { "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": "
We will review your information as soon as possible. If approved, you will receive an email from us with next steps.

You can safely close this tab.
" }, "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 } ``` ::: :::WorkflowBlockItem ### 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 curl 'https://app.getroster.com/v1/api/common/countries' \ -H 'authorization: clientKey e6Ys9wezVp7OQfcuQAjQjES4YAYs3Q| clientSecret Uqa9FQpmERXUVy23ZOlEIg26xLQK3o' \ -H 'origin: https://apply.getroster.com' \ ``` ::: :::WorkflowBlockItem ### Submit an application via API Use this endpoint to submit an application form via POST request. **Request:** ```curl 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": "jane@example.com", "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:** ```javascript { "success": true, "message": null, "errorCode": 0, "errorLevel": 0, "errorType": 0 } ``` ::: :::: *** ## Troubleshooting **Common issues:** 1. **Invalid form key**: Ensure you're using the correct form key from the program settings 2. **Missing required fields**: Check Step 1 response to confirm all required fields are included in your submission 3. **Invalid field values**: For fields with specific options (like dropdowns), ensure you're using exact values from the form structure 4. **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.