1. Introduction

Congrats you are about to work with the most mobility friendly system:

- Why do dragons sleep during the day?

- So they can fight knights

;-)

Welcome to the API Documentation for Joinup Customers!

Our API allows you to create, update or disable employees and to create, update or delete cost centers

We have language bindings in Shell, Python & Java, but it is up to you to use any programming language (Python, Java, Ruby, Javascript, etc). You will find code examples in the right dark area.

2. Authentication & Authorization

To authorization, use this code when we are creating an user:

curl "api_endpoint_here" \
  -H "Authorization: JWT beep-beep-beep-beep-beep"

import requests

headers = {
    'Authorization': 'JWT beep-beep-beep-beep-beep',
}

response = requests.get('http://api_endpoint_here', headers=headers)

import java.io.IOException;
import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

class Main {

    public static void main(String[] args) throws IOException {
        URL url = new URL("api_endpoint_here");
        HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
        httpConn.setRequestMethod("GET");

        httpConn.setRequestProperty("Authorization", "JWT beep-beep-beep-beep-beep");

        InputStream responseStream = httpConn.getResponseCode() / 100 == 2
                ? httpConn.getInputStream()
                : httpConn.getErrorStream();
        Scanner s = new Scanner(responseStream).useDelimiter("\\A");
        String response = s.hasNext() ? s.next() : "";
        System.out.println(response);
    }
}

Make sure to replace beep-beep-beep-beep-beep with your private token.

Joinup API expects for the token to be included in all API requests to the server in a header that looks like the following:

Authorization: beep-beep-beep-beep-beep

You must replace beep-beep-beep-beep-beep with your token.

3. Employees

3.1 HTTP Request

POST https://api.joinupbackend/api/company/employees/

This endpoint creates, updates or disables employees.

This endpoint supports a maximum of 50 employees.

This endpoint can be called 1 time per minute.

This endpoint (in production environment) sends a report with the result. It is possible add a customer email.

3.2 Configuration Company Group

curl "https://api.joinupbackend/api/company/employees/" \
  -H "Authorization: beep-beep-beep-beep-beep" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '[
        {
          "base_email":"test@example.com",
          "name": "Test",
          "operation": "onboarding",
          "company_name": "Company 1",
          "flexible": true,
          ...
        },
        {
          "base_email":"test2@example.com", 
          "name": "Test 2",
          "operation": "offboarding",
          "company_name": "Company 1",
          ...
        },
        {
          "base_email":"test3@example.com", 
          "name": "Test 3",
          "operation": "updated",
          "company_name": "New company",
          "flexible": true,
          ...
        },
        ...
  ]'

import requests

headers = {
    'Authorization': 'beep-beep-beep-beep-beep',
    'Content-Type': 'application/json',
}

json_data = [
    {
      "base_email":"test@example.com", 
      "name": "Test",
      "operation": "onboarding",
      "company_name": "Company 1",
      "flexible": True,
      ...
    },
    {
      "base_email":"test2@example.com", 
      "name": "Test 2",
      "operation": "offboarding",
      "company_name": "Company 1",
      ...
    },
    {
      "base_email":"test3@example.com", 
      "name": "Test 3",
      "operation": "updated",
      "company_name": "New company",
      "flexible": True,
      ...
    },
    ...
  ]

response = requests.post(
  'https://api.joinupbackend/api/company/employees/',
  headers=headers, json=json_data)


import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.List;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.joinupbackend/api/company/employees/";
        String token = "beep-beep-beep-beep-beep";
        List<Map<String, Object>> data = List.of(
            Map.of(
                "base_email", "test@example.com",
                "name", "Test",
                "operation", "onboarding",
                "company_name", "Company 1",
                "flexible", true,
                ...
            ),
            Map.of(
                "base_email", "test2@example.com",
                "name", "Test 2",
                "operation", "offboarding",
                "company_name", "Company 1",
                ...
            ),
            Map.of(
                "base_email", "test3@example.com",
                "name", "Test 3",
                "operation", "updated",
                "company_name", "New company",
                "flexible", true,
                ...
            ),
            ...
        );

        ObjectMapper mapper = new ObjectMapper();
        String requestBody = mapper.writeValueAsString(data);

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", token)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    }
}

The above command returns JSON structured like this:

    {
      "message": "Bulk task started!"
    }

Use this section if Joinup system has configured a Company group for your mobility platform

Attribute	Required	Description
operation	Yes	It can be onboarding (to create), offboarding (to disable) or updated (to update).
flexible	No. Default is false	Used when operation is onboarding or offboarding. It works like a create or update
base_email	Yes	Employee email. Used to search for an employee when operation is updated or offboarding. This field can not be updated (via API)
name	Yes	Employee Name
company_name	company_name or company_cif are required	Name of company. If there is not any company with this name our system will create a company with this name belonging to your Company Group
company_cif	company_name or company_cif are required	Spanish Tax Identification Number (CIF). If there is not any company with this CIF our system will create a company with this CIF belonging to your Company Group
other fields	No	cost_center, service_reason, management, section etc. There are a lot of employee fields. Please if you need to save more info contact the Joinup team. We will indicate what is the best field for your case.

3.3 Configuration Company

curl "https://api.joinupbackend/api/company/employees/" \
  -H "Authorization: beep-beep-beep-beep-beep" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '[
        {
          "base_email":"test@example.com",
          "name": "Test",
          "operation": "onboarding",
          "flexible": true,
          ...
        },
        {
          "base_email":"test2@example.com", 
          "name": "Test 2",
          "operation": "offboarding"
        },
        {
          "base_email":"test3@example.com", 
          "name": "Test 3",
          "operation": "updated",
          "flexible": true,
          ...
        },
        ...
  ]'

import requests

headers = {
    'Authorization': 'beep-beep-beep-beep-beep',
    'Content-Type': 'application/json',
}

json_data = [
    {
      "base_email":"test@example.com", 
      "name": "Test",
      "operation": "onboarding",
      "flexible": True,
      ...
    },
    {
      "base_email":"test2@example.com", 
      "name": "Test 2",
      "operation": "offboarding"
    },
    {
      "base_email":"test3@example.com", 
      "name": "Test 3",
      "operation": "updated",
      "flexible": True,
      ...
    },
    ...
  ]

response = requests.post(
  'https://api.joinupbackend/api/company/employees/',
  headers=headers, json=json_data)


import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.List;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.joinupbackend/api/company/employees/";
        String token = "beep-beep-beep-beep-beep";
        List<Map<String, Object>> data = List.of(
            Map.of(
                "base_email", "test@example.com",
                "name", "Test",
                "operation", "onboarding",
                "flexible", true,
                ...
            ),
            Map.of(
                "base_email", "test2@example.com",
                "name", "Test 2",
                "operation", "offboarding"
            ),
            Map.of(
                "base_email", "test3@example.com",
                "name", "Test 3",
                "operation", "updated",
                "flexible", true,
                ...
            ),
            ...
        );

        ObjectMapper mapper = new ObjectMapper();
        String requestBody = mapper.writeValueAsString(data);

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", token)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    }
}

The above command returns JSON structured like this:

    {
      "message": "Bulk task started!"
    }

Use this section if Joinup system has configured a single company for your mobility platform

Attribute	Required	Description
operation	Yes	It can be onboarding (to create), offboarding (to disable) or updated (to update).
flexible	No. Default is false	Used when operation is onboarding or offboarding. It works like a create or update
base_email	Yes	Employee email. Used to search for an employee when operation is updated or offboarding. This field can not be updated (via API)
name	Yes	Employee Name
other fields	No	cost_center, service_reason, management, section etc. There are a lot of employee fields. Please if you need save more info contact with Joinup team. We will indicate what is the best field for your case.

3.4 Status codes

Status Code	Meaning
202	Accepted indicates that a request has been accepted for processing, but processing has not been completed or may not have started. The request will be proccess in background.
400	Bad Request indicates that the server would not process the request due to something the server considered to be a client error. The errors are indicated in the response.
413	Content Too Large indicates that the request entity was larger than limits defined by server: 50 employees.
429	Too Many Requests indicates the client has sent another request in less than 1 minute ago.

4. Cost centers

4.1 HTTP Request

POST https://api.joinupbackend/api/company/cost-centers/

This endpoint creates, updates or deletes cost centers.

This endpoint supports a maximum of 50 cost centers.

This endpoint can be called 1 time per minute.

This endpoint (in production environment) sends a report with the result. It is possible add a customer email.

4.2 Configuration Company Group

curl "https://api.joinupbackend/api/company/cost-centers/" \
  -H "Authorization: beep-beep-beep-beep-beep" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '[
        {
          "name": "Test",
          "operation": "onboarding",
          "company_name": "Company 1",
          "flexible": true,
          ...
        },
        {
          "name": "Test 2",
          "operation": "offboarding",
          "company_name": "Company 1",
          ...
        },
        {
          "name": "Test 3",
          "operation": "updated",
          "company_name": "New company",
          "flexible": true,
          ...
        },
        ...
  ]'

import requests

headers = {
    'Authorization': 'beep-beep-beep-beep-beep',
    'Content-Type': 'application/json',
}

json_data = [
    {
        "name": "Test",
        "operation": "onboarding",
        "company_name": "Company 1",
        "flexible": True,
        ...
    },
    {
        "name": "Test 2",
        "operation": "offboarding",
        "company_name": "Company 1",
        ...
    },
    {
        "name": "Test 3",
        "operation": "updated",
        "company_name": "New company",
        "flexible": True,
        ...
    },
    ...
  ]

response = requests.post(
  'https://api.joinupbackend/api/company/cost-centers/',
  headers=headers, json=json_data)


import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.List;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.joinupbackend/api/company/cost-centers/";
        String token = "beep-beep-beep-beep-beep";
        List<Map<String, Object>> data = List.of(
            Map.of(
                "name", "Test",
                "operation", "onboarding",
                "company_name", "Company 1",
                "flexible", true,
                ...
            ),
            Map.of(
                "name", "Test 2",
                "operation", "offboarding",
                "company_name", "Company 1",
                ...
            ),
            Map.of(
                "name", "Test 3",
                "operation", "updated",
                "company_name", "New company",
                "flexible", true,
                ...
            ),
            ...
        );

        ObjectMapper mapper = new ObjectMapper();
        String requestBody = mapper.writeValueAsString(data);

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", token)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    }
}

The above command returns JSON structured like this:

    {
      "message": "Bulk task started!"
    }

Use this section if Joinup system has configured a Company group for your mobility platform

Attribute	Required	Description
operation	Yes	It can be onboarding (to create), offboarding (to delete) or updated (to update).
flexible	No. Default is false	Used when operation is onboarding or offboarding. It works like a create or update
name	Yes	Cost center. Used to search for an cost center when operation is updated or offboarding. This field can not be updated (via API)
company_name	No	Name of company. If there is not any company with this name our system will create a company with this name belonging to your Company Group
company_cif	No	Spanish Tax Identification Number (CIF). If there is not any company with this CIF our system will create a company with this CIF belonging to your Company Group

4.3 Configuration Company

curl "https://api.joinupbackend/api/company/cost-centers/" \
  -H "Authorization: beep-beep-beep-beep-beep" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '[
        {
          "name": "Test",
          "operation": "onboarding",
          "flexible": true
        },
        {
          "name": "Test 2",
          "operation": "offboarding"
        },
        {
          "name": "Test 3",
          "operation": "updated",
          "flexible": true
        },
        ...
  ]'

import requests

headers = {
    'Authorization': 'beep-beep-beep-beep-beep',
    'Content-Type': 'application/json',
}

json_data = [
    {
        "name": "Test",
        "operation": "onboarding",
        "flexible": True
    },
    {
        "name": "Test 2",
        "operation": "offboarding"
    },
    {
        "name": "Test 3",
        "operation": "updated",
        "flexible": True
    },
    ...
  ]

response = requests.post(
  'https://api.joinupbackend/api/company/cost-centers/',
  headers=headers, json=json_data)


import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.util.List;
import java.util.Map;
import com.fasterxml.jackson.databind.ObjectMapper;

public class Main {
    public static void main(String[] args) throws Exception {
        String url = "https://api.joinupbackend/api/company/cost-centers/";
        String token = "beep-beep-beep-beep-beep";
        List<Map<String, Object>> data = List.of(
            Map.of(
                "name", "Test",
                "operation", "onboarding",
                "flexible", true
            ),
            Map.of(
                "name", "Test 2",
                "operation", "offboarding"
            ),
            Map.of(
                "name", "Test 3",
                "operation", "updated",
                "flexible", true
            ),
            ...
        );

        ObjectMapper mapper = new ObjectMapper();
        String requestBody = mapper.writeValueAsString(data);

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Authorization", token)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody))
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    }
}

The above command returns JSON structured like this:

    {
      "message": "Bulk task started!"
    }

Use this section if Joinup system has configured a single company for your mobility platform

Attribute	Required	Description
operation	Yes	It can be onboarding (to create), offboarding (to delete) or updated (to update).
flexible	No. Default is false	Used when operation is onboarding or offboarding. It works like a create or update
name	Yes	Cost center. Used to search for an cost center when operation is updated or offboarding. This field can not be updated (via API)

4.4 Status codes

Status Code	Meaning
202	Accepted indicates that a request has been accepted for processing, but processing has not been completed or may not have started. The request will be proccess in background.
400	Bad Request indicates that the server would not process the request due to something the server considered to be a client error. The errors are indicated in the response.
413	Content Too Large indicates that the request entity was larger than limits defined by server: 50 cost centers.
429	Too Many Requests indicates the client has sent another request in less than 1 minute ago.