User Management API

Date: 13/03/2024 – 16h00

• GraphQL API
• Authentication
• Pagination
  • Limits
• Employee number
• Workflow
• Endpoints
  • Staging
  • Production
• Rate limitation
• Mutations
  • Login
  • Logout
  • Refresh token
  • Create a company
  • Create or Update a company
  • Create a department
  • Create or Update an employee
  • Create or Update a dependent
  • Set the off boarding date of an employee
• Queries
  • Fetch all employees by company and department
  • Fetch all employees by company
  • Search for the employee by external id
  • Search for the department by external id
  • Search for the company by external id

GraphQL API

• The User Management API is foloowing the graphQL principles
  • All requests are POST request to only one endpoint
  • The body of your requests should contain:
    • query: a string of the graphQL query you want to run
    • variables: a JSON dictionnairy of variables you may use in the query

Authentication

• You need to get your access Token (JWT) by using the login mutation
• Your access token will expires after a few hours
• You need to use the refreshToken mutation to refresh your access token
• You can revoke your access token at anytime with the logout mutation
• You have to use your access token as a Bearer in the header of your requests

{
  "Authorization": "Bearer <access_token>"
}

Pagination

• For each list you can query the pageInfo data which gives you some cursors you can use with before and after

{
  companies(first: 2) {
    totalCount
    pageInfo {
      startCursor
      endCursor
      hasNextPage
    }
    edges {
      node {
        id
        name
      }
    }
  }
}

• Then to query the next page, just use the endCursor value for the after parameter

{
  companies(first: 2, after: "YXJyYXljb25uZWN0aW9uOjE=") {
    totalCount
    pageInfo {
      startCursor
      endCursor
      hasNextPage
    }
    edges {
      node {
        id
        brand
      }
    }
  }
}

Limits

You won’t be able to fetch more than the following limits for the follwoing objects:

• Companies: 5
  You then need to use the pagination to fetch the next elements.

Employee number

• The key field to sync your database and ours is the employee_number. It’s a string of your internal ID. It will be associated with a record in our DB. You need to use this employee number every time you want to sync our databases
• All employee numbers should be unique inside a company
• 2 employees in 2 different

Workflow

1. Create a company with the createCompany mutation
2. Create a departement within this company with the createDepartment mutation
3. Create or update an employee with the createOrUpdateEmployee
   1. You will have to provide an onboarding date. Before this date, the access to the system will be blocked
4. When a user is leaving, you can set an offboarding date to this employee and after this date he won’t have access to the system
5. You can query the real onboarded date of an employee by using the company and the employee number

Endpoints

• You can navigate to the endpoints below with your browser to access a graphQL UI where you can test your queries and access a real time documentation

Staging

• To test your implementation, please use our staging endpoints: https://api-staging.healthmov.com/um_graphql

Production

• The final endpoint to use is: https://api.healthmov.com/um_graphql
• Warning: a staging access tokens cannot be used in production and vice versa

Rate limitation

• All the mutations are rate limited to avoid overwhelming our database
  • You can create 1 company per minute
  • You can create 1 departemnt per minute
  • You can create 50 employees per minute

Mutations

Login

• NO AUTHENTICATION

mutation {
    login(username: String!, password: String!) {
        ok
        accessToken
        accessTokenExpirationDate
        refreshToken
        refreshTokenExpirationDate
    }
}

Logout

mutation {
    logout {
      ok
    }
}

Refresh token

• WARNING: you need to send the refresh token in the Authentication header (as Bearer). Do not use the access token in the header

mutation {
    refreshToken
      {
        ok
        accessToken
        accessTokenExpirationDate
        refreshToken
        refreshTokenExpirationDate
    }
}

Create a company

mutation createCompany($companyName: String!, $logoUrl: String!, $externalId: String) {
  createCompany(companyName: $companyName, logoUrl: $logoUrl, externalId: $externalId) {
    company {
      id
      name
      logoUrl
    }
  }
}

variables = {
    "companyName": "your company name",
    "logoUrl": "your logo url",
    "externalId": "an ID from your DB (optional)"
}

Create or Update a company

mutation createOrUpdateCompany($companyName: String!, $logoUrl: String!, $externalId: String) {
  createOrUpdateCompany(companyName: $companyName, logoUrl: $logoUrl, externalId: $externalId) {
    company {
      id
      name
      logoUrl
    }
  }
}

variables = {
    "companyName": "your company name",
    "logoUrl": "your logo url",
    "externalId": "an ID from your DB (optional)"
}

Create a department

• The companyId is the id returned by the createCompany mutation

mutation createDepartment($companyId: ID!, $departmentName: String!, $externalId: String) {
  createDepartment(companyId: $companyId, departmentName: $departmentName, externalId: $externalId) {
    department {
      id
      name
    }
  }
}

variables = {
    "companyId": "ID!",
    "departmenetName": "your department name inside the company"
    "externalId": "an ID from your DB (optional)"
}

Create or Update an employee

• The departmentId and the companyId can be retreive with the companies query
• All parameters are mandatory, except phoneNumber and dependents (= [])

InputDependentObject:
    $firstName: String!
    $lastName: String
    $birthdate: Date!
    $externalId: String
    $email: String
    $dateOfOnboarding: Date
    $dateOfOffboarding: Date

mutation createOrUpdateEmployee(
  $companyId: ID!, 
  $departmentId: ID!, 
  $dateOfOnboarding: Date!, 
  $dateOfOffboarding: Date,
  $email: String!, 
  $employeeNumber: String!, 
  $firstName: String!, 
  $lastName: String!, 
  $phoneNumber: String,
  $dependents: [InputDependentObject],
  $externalId: String,
  birthdate: Date) {
  createOrUpdateEmployee(
    companyId: $companyId, 
    departmentId: $departmentId, 
    email: $email, 
    phoneNumber: $phoneNumber, 
    firstName: $firstName, 
    lastName: $lastName, 
    employeeNumber: $employeeNumber, 
    dateOfOnboarding: $dateOfOnboarding,
    dateOfOffboarding: $dateOfOffboarding,
    dependents: $dependents,
    externalId: $externalId,
    birthdate: $birthdate) {
    employee {
      id
      birthdate
      dependents {
    	  edges {
    	    node {
    	      id
            firstName
            lastName
            birthdate
    	    }
    	  }
    	}
      dependentsInfos {
        edges {
          node {
            id
            firstName
            lastName
            birthdate
          }
        }
      }
    }
  }
}

variables = {
    "companyId": "ID!",
    "departmenetId": "ID!",
    "dateOfOnboarding": "2022-01-01", 
    "dateOfOffboarding": "2024-01-01"
    "email": "foo@bar.com", 
    "employeeNumber": "123456ABCDEF", 
    "firstName": "Foo", 
    "lastName": "Bar", 
    "phoneNumber": "+971123456789",
    "dependents": [{ "birthdate": "1972-08-03", "firstName": "Foo", "lastName": "Bar"}, { "birthdate": "2000-01-01"}],
    "externalId": "an ID from your DB (optional)"
}

Create or Update a dependent

• All parameters are mandatory, except phoneNumber, dateOfOnboarding and dateOfOffboarding

mutation addOrUpdateDependent(
 	$birthdate: Date!,
 	$dependentEmail: String!,
	$dependentFirstName: String!,
	$dependentLastName: String!,
	$parentEmail: String!,
	$dependentPhone: String,
	$externalId: String,
  $dateOfOnboarding: Date, 
  $dateOfOffboarding: Date
	) {
  addOrUpdateDependent(
    birthdate: $birthdate, 
    parentEmail: $parentEmail, 
    dependentEmail: $dependentEmail, 
    dependentFirstName: $dependentFirstName, 
    dependentLastName: $dependentLastName,
    dependentPhone: $dependentPhone,
    externalId: $externalId,
    dateOfOnboarding: $dateOfOnboarding,
    dateOfOffboarding: $dateOfOffboarding) {
    employee {
      id
    }
  }
}

variables = {
    "birthdate": "2000-01-01",
    "dependentEmail": "dependent@bar.com",
    "dependentFirstName": "foo",
    "dependentLastName": "bar", 
    "parentEmail": "parent@bar.com",
    "dependentPhone": "+971123456789",
    "dateOfOnboarding": "2024-01-01 (optional)",
    "dateOfOffboarding": "2030-01-01 (optional)",
    "externalId": "an ID from your DB (optional)"
}

Set the off boarding date of an employee

mutation setOffboardingDate($employeeId: ID!, $dateOfOffboarding: Date!) {
  setOffboardingDate(employeeId: $employeeId, dateOfOffboarding:$dateOfOffboarding) {
    employee {
        id
        dateOfOffboarding
    }
  }
}

variables = {
    "employeeId": "ID!",
    "dateOfOffboarding": "2022-01-01"
}

Queries

Fetch all employees by company and department

{
  companies {
    edges {
      node {
        id
        name
        logoUrl
        departments {
          edges {
            node {
              id
              name
              employees {
                edges {
                  node {
                    id
                    employeeNumber
                    dateOfOnboarding
                    dateOfOffboarding
                    onboardedAt  
                    nbDependents
                    nbDependentsOnboarded
                    nbDependentsOffboarded
                    dependents {
                      edges{
                        node{
                          id
                          birthdate
                          email
                          firstName
                          lastName
                          phoneNumber
                          employeeNumber
                          dateOfOnboarding
                          dateOfOffboarding
                          onboardedAt  
                          nbDependents
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Fetch all employees by company

{
  companies {
    edges {
      node {
        id
        name
        logoUrl
        employees {
          edges {
            node {
              id
              employeeNumber
              dateOfOnboarding
              dateOfOffboarding
              onboardedAt  
              nbDependents
              nbDependentsOnboarded
              nbDependentsOffboarded
              dependents {
                edges{
                  node{
                    id
                    birthdate
                    email
                    firstName
                    lastName
                    phoneNumber
                    employeeNumber
                    dateOfOnboarding
                    dateOfOffboarding
                    onboardedAt  
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Search for the employee by external id

{
  searchEmployee(externalId: "your ID here") {
    id
  }
}

Search for the department by external id

{
  searchDepartment(externalId: "your ID here") {
    id
  }
}

Search for the company by external id

{
  searchCompany(externalId: "your ID here") {
    id
  }
}