Get active employees by service

This endpoint retrieves information about all active employees within a service during a specified period.

GET /api/v2/businesses/{businessId}/services/{serviceId}/employees/between?from={yyyy-MM-dd}&to={yyyy-MM-dd}

If the data included in the request is correct —both businessId and serviceId—, the response will contain the list of employees in the service with all the defined information for them.

Response example

  • Example 1

  • Example 2

[
    {
        "name": "Theodore",
        "surname": "Hayes",
        "email": "theohayes@bsn.com",
        "birthday": "1989-09-10",
        "employeeId": "209_14",
        "virtual": false
    },
    {
        "name": "Melanie",
        "surname": "Jenkins",
        "employeeId": "555",
        "virtual": false
    },
    {
        "name": "Andrea",
        "surname": "Meyer",
        "employeeId": "444",
        "metadata": {},
        "virtual": false
    },
    {
        "name": "Mariane",
        "surname": "Ortega Acevedo",
        "birthday": "2004-01-02",
        "employeeId": "1006350",
        "virtual": false
    }
]
[
    {
        "name": "ARIANA",
        "surname": "VISMARA",
        "group": "Responsible",
        "employeeId": "1493432",
        "metadata": {
            "language": "english"
        },
        "virtual": false
    },
    {
        "name": "CLARA",
        "surname": "SANDERS",
        "group": "Merchandising",
        "employeeId": "5690921",
        "metadata": {
            "or": "WOMAN"
        },
        "virtual": false
    },
    {
        "name": "MAYA",
        "surname": "SANTORO",
        "group": "General",
        "employeeId": "9454863",
        "virtual": false
    }
]
Details

  • name: employee’s first name.

  • surname: employee’s last name(s).

  • group: group the employee belongs to.

  • email: employee’s email address.

  • birthday: date of birth in yyyy-MM-dd format.

  • employeeId: employee identifier in the external system.

  • metadata: additional data about the employee. The structure of this field must be previously configured at the business level by the Orquest team.

  • seniority: employee’s seniority date in yyyy-MM-dd format.

  • virtual: determines whether this is a real employee or a virtual one used, for example, to run simulations.

As shown in the example, the request will return the information defined in the system, so there may be non-mandatory fields that do not appear in the response.

Metadata will only appear in businesses that have previously configured this information.

Considerations

If the service indicated in the URL does not exist in the business, the request will return a 404 Not Found error, specifying not exits in the message.

If there are no employees in the indicated service, the request will return an empty array [].

Useful links

What is an employee?

What is a service association?

What is a contract? And a contract type?

How to integrate employees?