Add applicants via API

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" "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 { "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