This guide outlines how you can integrate with Forma's SCIM endpoint to automate the process of provisioning/de-provisioning employee information between your IDM system and Forma.
\nYour CSM and implementation manager will provide you with credentials to the Forma Admin Portal where you will be able to generate an API token for authenticating into our SCIM API endpoint.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"5679452","collectionId":"6108bb75-bd5c-47bc-9944-b62dad046ace","publishedId":"TVKBaK8F","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2020-09-21T07:14:50.000Z"},"item":[{"name":"Create User","id":"3faf58bb-0194-4985-bea7-d11568bb61f0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer {{SCIM_AUTHORIZATION_TOKEN}}"}],"body":{"mode":"raw","raw":"{\n \"active\": true,\n \"emails\": [\n {\n \"primary\": true,\n \"value\": \"test@twic.ai\"\n }\n ],\n \"externalId\": \"external identifier\",\n \"name\": {\n \"familyName\": \"Test\",\n \"givenName\": \"User\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\",\n \"urn:ietf:params:scim:schemas:extension:twic:2.0:User\",\n \"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\"\n ],\n \"title\": \"SDE 1\",\n \"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\": {\n \"department\": \"Engineering\",\n \"employeeNumber\": \"external_employee_id\",\n \"organization\": \"Twic Global\"\n },\n \"urn:ietf:params:scim:schemas:extension:twic:2.0:User\": {\n \"hire_date\": \"2022-02-01\",\n \"is_fulltime\": true,\n \"is_manager\": true,\n \"manager_email\": \"manager@twic.ai\",\n \"office_country\": \"US\",\n \"office_city\": \"San Franscisco\",\n \"cost_center_code\": \"GBS\",\n \"cost_center_name\": \"Twic Inc USA\",\n \"office_code\": \"FORMA GBS\",\n \"Custom has insurrance\": \"YES\",\n \"Custom number of kids\": 2\n },\n \"userName\": \"test@twic.ai\",\n \"profileUrl\": \"https://via.placeholder.com/140x100\",\n}"},"url":"https://{{SCIM_API_DOMAIN}}/scim/v2/Users","description":"Creating new user in Forma System.
Required Fields
Update user properties.
\n","urlObject":{"protocol":"https","path":["scim","v2","Users",":forma_user_id"],"host":["{{SCIM_API_DOMAIN}}"],"query":[],"variable":[{"description":{"content":"Forma user ID generated by Forma system on successful create user call.
\n","type":"text/plain"},"type":"any","value":"77c1ee43-2960-4a09-a93d-98eb2fcd379f","key":"forma_user_id"}]}},"response":[{"id":"19950292-3e0f-4bb3-94b3-4a393de97170","name":"Success Example : User title has changed.","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{SCIM_AUTHORIZATION_TOKEN}}"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"active\": true,\n \"externalId\": \"00u4p65a51CcN\",\n \"name\": {\n \"familyName\": \"Test\",\n \"givenName\": \"User\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\",\n \"urn:ietf:params:scim:schemas:extension:twic:2.0:User\",\n \"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\"\n ],\n \"title\": \"SDE 2\",\n \"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\": {\n \"department\": \"Engineering\",\n \"employeeNumber\": \"twic-eng-12344\",\n \"organization\": \"Twic Global\"\n },\n \"urn:ietf:params:scim:schemas:extension:twic:2.0:User\": {\n \"is_fulltime\": true,\n \"office_country\": \"US\"\n }\n}"},"url":{"raw":"https://{{SCIM_API_DOMAIN}}/scim/v2/Users/:forma_user_id","protocol":"https","host":["{{SCIM_API_DOMAIN}}"],"path":["scim","v2","Users",":forma_user_id"],"variable":[{"key":"forma_user_id","value":"77c1ee43-2960-4a09-a93d-98eb2fcd379f","description":"Forma user ID generated by Forma system on successful create user call."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"X-Powered-By","value":"Express"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"512"},{"key":"ETag","value":"W/\"200-TPR1rwnillP8JAVIt1i07BjKkfg\""},{"key":"Date","value":"Mon, 21 Sep 2020 05:59:26 GMT"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"status\": 200,\n \"active\": true,\n \"externalId\": \"00u4p65a51CcN\",\n \"name\": {\n \"familyName\": \"Test\",\n \"givenName\": \"User\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"title\": \"SDE 2\",\n \"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\": {\n \"department\": \"Engineering\",\n \"employeeNumber\": \"twic-eng-12344\",\n \"organization\": \"Twic Global\"\n },\n \"urn:ietf:params:scim:schemas:extension:twic:2.0:User\": {\n \"is_fulltime\": true,\n \"office_country\": \"US\"\n },\n \"is_twic_eligible\": true,\n \"id\": \"77c1ee43-2960-4a09-a93d-98eb2fcd379f\"\n}"},{"id":"3b3aed83-77c3-4664-9d86-5492c8a2a889","name":"Failure Example: User not found","originalRequest":{"method":"PUT","header":[{"key":"Authorization","value":"Bearer {{SCIM_AUTHORIZATION_TOKEN}}"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"active\": true,\n \"externalId\": \"00u4p65a51CcN\",\n \"name\": {\n \"familyName\": \"Test\",\n \"givenName\": \"User\"\n },\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\",\n \"urn:ietf:params:scim:schemas:extension:twic:2.0:User\",\n \"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\"\n ],\n \"title\": \"SDE 2\",\n \"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\": {\n \"department\": \"Engineering\",\n \"employeeNumber\": \"twic-eng-12344\",\n \"organization\": \"Twic Global\"\n },\n \"urn:ietf:params:scim:schemas:extension:twic:2.0:User\": {\n \"is_fulltime\": true,\n \"office_country\": \"US\"\n }\n}"},"url":{"raw":"https://{{SCIM_API_DOMAIN}}/scim/v2/Users/:forma_user_id","protocol":"https","host":["{{SCIM_API_DOMAIN}}"],"path":["scim","v2","Users",":forma_user_id"],"variable":[{"key":"forma_user_id","value":"missing-user-id","description":"Any missing id not in Forma system"}]}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"X-Powered-By","value":"Express"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"118"},{"key":"ETag","value":"W/\"76-ooNr7V2f5UvjwlfWG0jTsTojFdk\""},{"key":"Date","value":"Mon, 21 Sep 2020 06:03:46 GMT"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"detail\": \"Not Found: \\\"User does not exist\\\"\",\n \"status\": 404\n}"}],"_postman_id":"22242b86-f04d-47d0-a56c-5afa7c22b4a4"},{"name":"Get Single User","id":"379eba21-6fc0-4c62-b23e-f0a0b2ce981c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{SCIM_AUTHORIZATION_TOKEN}}"}],"url":"https://{{SCIM_API_DOMAIN}}/scim/v2/Users/:forma_user_id","description":"Get single user by id
\n","urlObject":{"protocol":"https","path":["scim","v2","Users",":forma_user_id"],"host":["{{SCIM_API_DOMAIN}}"],"query":[],"variable":[{"description":{"content":"Forma user ID generated by Forma system on successful create user call.
\n","type":"text/plain"},"type":"any","value":"77c1ee43-2960-4a09-a93d-98eb2fcd379f","key":"forma_user_id"}]}},"response":[{"id":"2193e506-edd2-4c11-91fe-868acf3cdccd","name":"Failure Example : User not found","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{SCIM_AUTHORIZATION_TOKEN}}"}],"url":{"raw":"https://{{SCIM_API_DOMAIN}}/scim/v2/Users/:forma_user_id","protocol":"https","host":["{{SCIM_API_DOMAIN}}"],"path":["scim","v2","Users",":forma_user_id"],"variable":[{"key":"forma_user_id","value":"missing-user-id","description":"Any missing id not in Forma system"}]}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"X-Powered-By","value":"Express"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"118"},{"key":"ETag","value":"W/\"76-ooNr7V2f5UvjwlfWG0jTsTojFdk\""},{"key":"Date","value":"Mon, 21 Sep 2020 07:03:09 GMT"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"detail\": \"Not Found: \\\"User does not exist\\\"\",\n \"status\": 404\n}"},{"id":"4b79f8d8-c1b8-48c7-8abe-de4140e6986c","name":"Success Example","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{SCIM_AUTHORIZATION_TOKEN}}"}],"url":{"raw":"https://{{SCIM_API_DOMAIN}}/scim/v2/Users/:forma_user_id","protocol":"https","host":["{{SCIM_API_DOMAIN}}"],"path":["scim","v2","Users",":forma_user_id"],"variable":[{"key":"forma_user_id","value":"77c1ee43-2960-4a09-a93d-98eb2fcd379f","description":"Forma user ID generated by Forma system on successful create user call."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"X-Powered-By","value":"Express"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"800"},{"key":"ETag","value":"W/\"320-4teipHo6so0LlLufmkc+bolyOmM\""},{"key":"Date","value":"Mon, 21 Sep 2020 07:01:36 GMT"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"status\": 200,\n \"active\": true,\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"is_twic_eligible\": true,\n \"id\": \"77c1ee43-2960-4a09-a93d-98eb2fcd379f\",\n \"externalId\": \"00u4p65a51CcN\",\n \"meta\": {\n \"created\": \"2020-09-21T05:50:59.397Z\"\n },\n \"userName\": \"test-success@twic.ai\",\n \"name\": {\n \"givenName\": \"User\",\n \"familyName\": \"Test\"\n },\n \"displayName\": \"User Test\",\n \"title\": \"SDE 2\",\n \"profileUrl\": \"https://s3-us-west-1.amazonaws.com/twic.ai/avatar/default_avatar.png\",\n \"emails\": [\n {\n \"value\": \"test-success@twic.ai\",\n \"primary\": true\n }\n ],\n \"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User\": {\n \"organization\": \"Twic Global\",\n \"employeeNumber\": \"twic-eng-12344\",\n \"department\": \"Engineering\"\n },\n \"urn:ietf:params:scim:schemas:extension:twic:2.0:User\": {\n \"Custom number of kids\": 0,\n \"Custom is commuter eligible\": false,\n \"Custom title\": \"\"\n }\n}"}],"_postman_id":"379eba21-6fc0-4c62-b23e-f0a0b2ce981c"},{"name":"Get users","id":"aaaaa200-a5a7-45f4-ac14-7cab0b16e174","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{SCIM_AUTHORIZATION_TOKEN}}"}],"url":"https://{{SCIM_API_DOMAIN}}/scim/v2/Users?filter=userName max@joinforma.com&startIndex=1&limit=10","description":"Get users by query parameters
\n","urlObject":{"protocol":"https","path":["scim","v2","Users"],"host":["{{SCIM_API_DOMAIN}}"],"query":[{"description":{"content":"Supported keys are emails,userName,externalId
\n","type":"text/plain"},"key":"filter","value":"userName max@joinforma.com"},{"description":{"content":"Page number.
\n","type":"text/plain"},"key":"startIndex","value":"1"},{"description":{"content":"Results per page.
\n","type":"text/plain"},"key":"limit","value":"10"}],"variable":[]}},"response":[],"_postman_id":"aaaaa200-a5a7-45f4-ac14-7cab0b16e174"},{"name":"Delete user","id":"eb4de889-fd01-4baa-a897-a1940412e869","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{SCIM_AUTHORIZATION_TOKEN}}","type":"text"},{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":""},"url":"https://{{SCIM_API_DOMAIN}}/scim/v2/Users/:forma_user_id","description":"This will not hard delete user but mark user as active = false.
\n","urlObject":{"protocol":"https","path":["scim","v2","Users",":forma_user_id"],"host":["{{SCIM_API_DOMAIN}}"],"query":[],"variable":[{"description":{"content":"Forma user ID generated by Forma system on successful create user call.
\n","type":"text/plain"},"type":"any","value":"77c1ee43-2960-4a09-a93d-98eb2fcd379f","key":"forma_user_id"}]}},"response":[{"id":"5a5777f6-20dc-486e-802c-c78258fa4448","name":"Failure Example : User not found","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{SCIM_AUTHORIZATION_TOKEN}}","type":"text"},{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"https://{{SCIM_API_DOMAIN}}/scim/v2/Users/:forma_user_id","protocol":"https","host":["{{SCIM_API_DOMAIN}}"],"path":["scim","v2","Users",":forma_user_id"],"variable":[{"key":"forma_user_id","value":"missing-user-id","description":"Any missing id not in Forma system"}]}},"status":"Not Found","code":404,"_postman_previewlanguage":"json","header":[{"key":"X-Powered-By","value":"Express"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"118"},{"key":"ETag","value":"W/\"76-ooNr7V2f5UvjwlfWG0jTsTojFdk\""},{"key":"Date","value":"Mon, 21 Sep 2020 07:18:03 GMT"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"schemas\": [\n \"urn:ietf:params:scim:api:messages:2.0:Error\"\n ],\n \"detail\": \"Not Found: \\\"User does not exist\\\"\",\n \"status\": 404\n}"},{"id":"e20fec34-b1ac-4096-975c-6fdd983a4e9a","name":"Success Example","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":"Bearer {{SCIM_AUTHORIZATION_TOKEN}}","type":"text"},{"key":"Content-Type","name":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":""},"url":{"raw":"https://{{SCIM_API_DOMAIN}}scim//v2/Users/:forma_user_id","protocol":"https","host":["{{SCIM_API_DOMAIN}}scim"],"path":["","v2","Users",":forma_user_id"],"variable":[{"key":"forma_user_id","value":"77c1ee43-2960-4a09-a93d-98eb2fcd379f","description":"Forma user ID generated by Forma system on successful create user call."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"X-Powered-By","value":"Express"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"170"},{"key":"ETag","value":"W/\"aa-LvX9XaqSA6yru4VRYHYCg1/9SqY\""},{"key":"Date","value":"Mon, 21 Sep 2020 07:16:51 GMT"},{"key":"Connection","value":"keep-alive"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"status\": 200,\n \"active\": false,\n \"is_twic_eligible\": false,\n \"schemas\": [\n \"urn:ietf:params:scim:schemas:core:2.0:User\"\n ],\n \"id\": \"77c1ee43-2960-4a09-a93d-98eb2fcd379f\"\n}"}],"_postman_id":"eb4de889-fd01-4baa-a897-a1940412e869"},{"name":"Patch User","id":"07272205-6e99-4061-b8c2-62764fdc7de7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[{"key":"Authorization","type":"text","value":"Bearer {{SCIM_AUTHORIZATION_TOKEN}}"},{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"Operations\": [\n {\n \"op\": \"replace\",\n \"value\": {\n \"active\": true\n }\n }\n ],\n \"schemas\": [\"urn:ietf:params:scim:api:messages:2.0:PatchOp\"]\n}"},"url":"https://{{SCIM_API_DOMAIN}}/scim/v2/Users/:forma_user_id","description":"Only support values are
active = true/false .
is_twic_eligible = true/false .