Wospee Integrations API

Version 2.0 draft

The Integrations API connects your systems to the integrations that Wospee runs for you on the Wospee Digital Platform: it exchanges files with the platform, starts integration functions and extracts data on line. It is a different product from the Core HR API, with its own credentials and its own addresses.

Access

The API uses OAuth 2.0, in the client credentials flow. Wospee gives you a client ID and a client secret: keep the secret safe, out of your code. To build and try an integration, ask for credentials on the test environment, which has addresses of its own.

  1. Ask the token endpoint for a token, with the client ID, the client secret and the scope wpdp_client_credentials/token, in a form body.
  2. Send the token in the Authorization header of every call: Authorization: Bearer <token>.
  3. Reuse the token until it expires (expires_in, in seconds: a token lasts one hour), then ask for a new one. Do not ask for a token for every call.
AddressProductionTest environment
Token endpointhttps://login.api.dp-wospee.com/oauth2/tokenhttps://login.api.wpdpwharol.com/oauth2/token
Callshttps://api.dp-wospee.com/apihttps://api.wpdpwharol.com/api
POST /oauth2/token HTTP/1.1
Host: login.api.dp-wospee.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client ID>&client_secret=<client secret>&scope=wpdp_client_credentials%2Ftoken
{
  "access_token": "eyJraWQiOiJ...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Calls

Every call is a POST to the same address, with the token and a JSON body. The Code key of the body names the function that the call runs:

CodeWhat the call does
@dummychecks that the token works (see Trying the connection)
S3sends, lists, downloads and deletes files (see Files)
Runstarts an integration function (see Running a function)
APIextractextracts data on line (see Extracting data)
POST /api HTTP/1.1
Host: api.dp-wospee.com
Authorization: Bearer eyJraWQiOiJ...
Content-Type: application/json

{ "Code": "@dummy" }

A tenant is one environment of a customer of the Wospee Digital Platform, usually a company. When your user works on more than one tenant or application, the body names them: TEGUID is the code of the tenant, for example TE9001, and APGUID the code of the application, for example AP001. With one of each, leave them out. A file always travels in the body as text, in base64.

Trying the connection

  • { "Code": "@dummy" } checks that the token works. The answer is the text "Welcome API Wospee is here!".
  • "@test": true, added to the body of any call, checks that your user may make that call, with its function and its operations, without making it. When it may, the answer is the text "Run in Test mode, you are perfectly configured!".

Files

Your tenant has a file area on the platform, divided into folders: an alternative to an SFTP site, to send files to your integrations and to collect what they produce. A file call has Code S3, and says what to do in Operation:

OperationWhat it does
Uploadsaves the files in the folder, and a copy of each in the backup folder
Downloadgives back the files
FilesListlists the files and the folders of a folder
Deletedeletes the files named, or with Match every file whose name contains that text
Upload-Deletesaves the files only in the backup folder: useful to keep them while a function processes them (see Running a function after a file call). Delete-Upload does the same: the upload always comes first

Upload and Delete are the only operations that go together; Download and FilesList always go alone. The keys of the body:

KeyWhat it carries
Codealways S3
Operationwhat to do, from the table above
Context.Directorythe folder; for an Upload alone it can be left out, and is then input
Context.FileName and Context.FileBodyone file: its name, with the extension, and its content in base64
Context.FilesNamemore files at once, a list of FileName and FileBody: only with Upload and Delete
Matchwith Delete: deletes every file whose name contains this text
daysBackup0 to keep no copy in the backup folder
Function and Userstart a function with the files, after the call (see Running a function after a file call)
  • Every upload also keeps a copy of the file in the backup folder of its folder, <folder>Backup, named YYYYMMDD-HHMMSS-<file name>.
  • A file name starts with a letter, a digit or _, and has an extension (^\w+.*\.\w+$).
  • Download and Delete by name need files that exist, and Delete with Match at least one file that matches: otherwise the answer is 404. FilesList and Match name no files.
{
  "Code": "S3",
  "Operation": "Upload",
  "Context": {
    "Directory": "input",
    "FileName": "employees.csv",
    "FileBody": "TmFtZTtTdXJuYW1lCg=="
  }
}
{
  "Code": "S3",
  "Operation": "Delete",
  "Match": "2026-10",
  "Context": {
    "Directory": "output"
  }
}

Upload and Delete answer 200 when every file went well. FilesList answers the lists Files and Directories: the files and the folders inside the folder, each with its path from the top of your file area. Files without an extension are not listed, and the answer stops at 1,000 entries.

{
  "Files": [
    "output/result.xlsx",
    "output/errors.csv"
  ],
  "Directories": [
    "output/2026/"
  ]
}

Download carries the files in Download.body.FilesName, each with FileName and FileBody:

{
  "Download": {
    "statusCode": 200,
    "body": {
      "FilesName": [
        {
          "FileName": "result.xlsx",
          "FileBody": "UEsDBBQABgAIAAAAIQ..."
        }
      ]
    }
  }
}

Running a function

Code Run starts one of your integration functions, the same ones that run on the platform, and answers at once, without waiting for the end: 200 with the text Your function has started successfully. The results reach a user in the Wospee Digital Platform.

{
  "Code": "Run",
  "Function": "FA9001",
  "User": "integrations.user",
  "Context": [
    {
      "FileName": "employees.csv",
      "FileBody": "TmFtZTtTdXJuYW1lCg=="
    }
  ]
}
KeyWhat it carries
Functionthe code of the function, which Wospee gives you
Userthe user name of the user who receives the results, one of the users of your company; without it, the one that Wospee set up for the function, otherwise the user of your credentials
Contextthe files for the function, a list of FileName and FileBody
other keysthe parameters of the function, when Wospee set it up to receive them

Your user needs both the function and Run.

Running a function after a file call

A file call that saves files can also start a function. With Function in its body, and User if you want, the platform runs the function with the files of the call, once they are saved; with Upload-Delete the files stay only in the backup folder.

{
  "Code": "S3",
  "Operation": "Upload-Delete",
  "Function": "FA9001",
  "Context": {
    "Directory": "input",
    "FilesName": [
      {
        "FileName": "employees.csv",
        "FileBody": "TmFtZTtTdXJuYW1lCg=="
      },
      {
        "FileName": "contracts.csv",
        "FileBody": "Q29kZTtUeXBlCg=="
      }
    ]
  }
}

Extracting data

Code APIextract reads data on line from the systems that your integrations use, typically Cezanne HR, as Wospee set up the extraction for you: which data, which fields, which parameters. Every parameter of the extraction is required, and travels in the body with its name, for example a company code:

{
  "Code": "APIextract",
  "Company": "100"
}

The answer has HEADER and ROW. HEADER.FIELDS lists the fields, each with its name, Field, and its type, Type, and HEADER.MYNUMROW says how many records there are; ROW holds the records, one object each. When Wospee has set up more than one extraction for you, INCODE in the body names the one to run.

Errors

A call that fails answers with an HTTP status and a short message in English in the body, sometimes as a JSON string. Programs decide from the status, not from the message.

StatusWhen
400a key of the body is missing or not valid, for example a file without FileBody in an Upload, or a file name that is not valid; or the function named in Code does not exist for your user
401the token is missing or not valid; or your user may not run the function, or one of its operations
402APIextract: the extraction is not set up for your tenant, or one of its parameters is missing
404the body has no Code; Context.Directory is missing; the files, or the files of Match, are not there; or Operation names nothing known
409your user works on more than one tenant or application: name them with TEGUID and APGUID
500an error on our side

Example in Python

import base64
import os

import requests

TOKEN_URL = "https://login.api.dp-wospee.com/oauth2/token"
API_URL = "https://api.dp-wospee.com/api"

# A token, with the credentials that Wospee gave you
answer = requests.post(TOKEN_URL, data={
    "grant_type": "client_credentials",
    "client_id": os.environ["WOSPEE_CLIENT_ID"],
    "client_secret": os.environ["WOSPEE_CLIENT_SECRET"],
    "scope": "wpdp_client_credentials/token",
})
answer.raise_for_status()
headers = {"Authorization": "Bearer " + answer.json()["access_token"]}

# Send a file to the folder input
with open("employees.csv", "rb") as f:
    content = base64.b64encode(f.read()).decode("ascii")
answer = requests.post(API_URL, headers=headers, json={
    "Code": "S3", "Operation": "Upload",
    "Context": {"Directory": "input", "FileName": "employees.csv", "FileBody": content},
})
answer.raise_for_status()

# List the files of the folder output, then download one
answer = requests.post(API_URL, headers=headers, json={
    "Code": "S3", "Operation": "FilesList", "Context": {"Directory": "output"},
})
print(answer.json()["Files"])
answer = requests.post(API_URL, headers=headers, json={
    "Code": "S3", "Operation": "Download",
    "Context": {"Directory": "output", "FileName": "result.xlsx"},
})
for item in answer.json()["Download"]["body"]["FilesName"]:
    with open(item["FileName"], "wb") as f:
        f.write(base64.b64decode(item["FileBody"]))