Skip to main content

User Management API

User Management API

Date: 18/02/2025 - 11h00

GraphQL API

  • The User Management API follows GraphQL principles:
    • All requests are POST requests to a single endpoint.
    • The body of your requests should contain:
      • query: a string of the GraphQL query you want to run
      • variables: a JSON dictionary of variables you may use in the query

Authentication

  • You need to obtain your access token (JWT) by using the login mutation.
  • Your access token will expire after a few hours.
  • You need to use the refreshToken mutation to refresh your access token.
  • You can revoke your access token at any time with the logout mutation.
  • You must use your access token as a Bearer token in the request header.
{
  "Authorization": "Bearer <access_token>"
}

Pagination

  • For each list, you can query the pageInfo data, which gives you cursors you can use with before and after.
{
  companies(first: 2) {
    totalCount
    pageInfo {
      startCursor
      endCursor
      hasNextPage
    }
    edges {
      node {
        id
        name
      }
    }
  }
}
  • To query the next page, use the endCursor value for the after parameter.
{
  companies(first: 2, after: "YXJyYXljb25uZWN0aW9uOjE=") {
    totalCount
    pageInfo {
      startCursor
      endCursor
      hasNextPage
    }
    edges {
      node {
        id
        brand
      }
    }
  }
}

Limits

You will not be able to fetch more than the following limits for the corresponding objects:

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

Employee number

  • The key field to synchronize your database and ours is the employee_number. It's a string containing 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 synchronize our databases.
  • All employee numbers should be unique within a company.
  • Two employees in two different companies can have the same employee number.

Workflow

  1. Create a company with the createCompany mutation.
  2. Create a department within this company with the createDepartment mutation.
  3. Create or update an employee with the createOrUpdateEmployee mutation.
    1. You have to provide an onboarding date. Before this date, access to the system will be blocked.
  4. When a user is leaving, you can set an offboarding date for this employee. After this date, they will no longer have access to the system.
  5. You can query the actual 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 real-time documentation.

Staging

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

Production

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

Rate limitation

  • All mutations are rate-limited to avoid overwhelming our database:
    • You can create 1 company per minute.
    • You can create 1 department per minute.
    • You can create 50 employees per minute.

Mutations

Login

  • NO AUTHENTICATION NEEDED 
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
    }
  }
}

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

Create or Update a company

  • If the dates are not provided, the dates will not be updated.
mutation createOrUpdateCompany(
  $companyName: String!,
  $logoUrl: String!,
  $externalId: String,
  $dateOfOnboarding: Date,
  $dateOfOffboarding: Date
) {
  createOrUpdateCompany(
    companyName: $companyName,
    logoUrl: $logoUrl,
    externalId: $externalId,
    dateOfOnboarding: $dateOfOnboarding,
    dateOfOffboarding: $dateOfOffboarding
  ) {
    company {
      id
      name
      logoUrl
      dateOfOnboarding
      dateOfOffboarding
    }
  }
}

{
  "companyName": "your company name",
  "logoUrl": "your logo url",
  "externalId": "an ID from your DB (optional)",
  "dateOfOnboarding": "2022-01-01",
  "dateOfOffboarding": "2024-01-01"
}

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
    }
  }
}

{
  "companyId": "ID!",
  "departmentName": "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 retrieved with the companies query.
  • All parameters are mandatory, except phoneNumber and dependents (default is []).
# InputDependentObject fields:
#   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
          }
        }
      }
    }
  }
}

{
  "companyId": "ID!",
  "departmentId": "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 dependentPhone, 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
    }
  }
}

{
  "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 offboarding date of an employee

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

{
  "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
  }
}
Back to top