Introduction

Welcome to the lemcal Developer Documentation.

Rate Limit

lemcal's API rate limits requests in order to prevent abuse and overload of our services.
Rate limits are applied on all routes and per api key performing the request.
The rate limits are 20 requests per 2 seconds.

The response provide any information you may need about it:

Example of values for the rate limit headers

{
  "Retry-After": 2,
  "X-RateLimit-Limit": 20,
  "X-RateLimit-Remaining": 7,
  "Retry-After" : "Tue Feb 16 2021 09:02:42 GMT+0100 (Central European Standard Time)"
}

Header	Description
Retry-After	The number of second in which you can retry
X-RateLimit-Limit	The maximum requests in that time
X-RateLimit-Remaining	The number of remaining requests you can make
X-RateLimit-Reset	The date when the rate limit will reset

Definitions

Meeting

A meeting is a scheduled engagement defined by a specific type, including details such as name, duration, and location, facilitating streamlined booking and organization between users.

Meeting Type

A meeting type is a customizable template that defines the specific details of a potential meeting. Users can create various meeting types to offer different options to those who want to book a meeting with them.

Lead

A lead is a person that you try to contact using lemlist.

Authentication

To authorize, use this code:

curl -X GET "http://api.lemcal.com/api/lemcal/me" \
     -H "Authorization: Basic $(echo -n 'userId:apiKey' | base64)"

All lemcal API routes are accessed via the dedicated subdomain api.lemcal.com.

Authentication is performed using the Basic authentication type in the Authorization header. The format for this header is username:password that can be obtained here.

Meetings

List booked meetings

This endpoint retrieves your booked meetings.

HTTP Request

curl -X GET "http://api.lemcal.com/api/lemcal/meetings" \
     -H "Authorization: Basic $(echo -n 'userId:apiKey' | base64)"

The above command returns JSON structured like this:


[
  {
      "_id": "mee_NSXBft76yJoMh5Bik",
      "userId": "usr_BuDuyx4chjoNfcmzM",
      "meetingTypeId": "met_4HdebtnSiwFpFb6BF",
      "providedInfos": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
      "eventId": "fkne3iuvmjsvi9cf746s39obfc",
      "start": "2023-03-24T15:30:00.000Z",
      "end": "2023-03-24T16:00:00.000Z",
      "lead": {
          "email": "alice@example.com",
          "firstName": "alice",
          "lastName": "smith",
      },
      "attendees": [
          {
              "email": "alice@example.com",
              "name": "alice",
              "type": "required",
              "response": "accepted"
          },
          {
              "email": "bob@example.com",
              "type": "required",
              "response": "accepted"
          }
      ],
      "createdAt": "2023-07-19T13:23:39.910Z"
  },
]

GET http://api.lemcal.com/api/lemcal/meetings

Query Parameters

Parameter	Type	Required	Description
`meetingTypeId`	string	No	Filter meetings by a specific meeting type.

Response

Parameter	Description
_id	Unique identifier for the meeting.
userId	Identifier for the user associated with the meeting.
meetingTypeId	Identifier for the type of meeting.
providedInfos	Additional text information about the meeting.
eventId	Unique identifier for the related event.
start	Start time of the meeting in ISO 8601 format.
end	End time of the meeting in ISO 8601 format.
lead.email	Lead's email address.
lead.firstName	Lead's first name.
lead.lastName	Lead's last name.
attendees	List of attendees for the meeting (includes email, name, type, response).
createdAt	Creation date and time of the meeting in ISO 8601 format.

Create a Hook

This endpoint allows you to create a hook to a specified target URL. Hooks can be associated with a specific meeting type or applied to any meeting type.

HTTP Request

POST http://api.lemcal.com/api/lemcal/hooks/

curl -X POST "http://api.lemcal.com/api/lemcal/hooks" \
     -H "Authorization: Basic $(echo -n 'userId:apiKey' | base64)" \
     -H "Content-Type: application/json" \
     -d '{
         "targetUrl": "http://example.com/callback",
         "meetingTypeId": "met_4HdebtnSiwFpFb6BF",
         "anyMeetingType": true
     }'

The above command returns JSON structured like this:


{
    "_id": "hoo_NSXBft76yJoMh5Bik",
    "targetUrl": "http://example.com/callback",
    "meetingTypeId": "met_4HdebtnSiwFpFb6BF",
    "anyMeetingType": true,
    "createdAt": "2022-10-17T07:43:50.740Z"
}

Request Body

Parameter	Type	Required	Description
`targetUrl`	string	Yes	The target URL for the hook. Must be a valid URL starting with `http://` or `https://`.
`meetingTypeId`	string	No	The ID of a specific meeting type to associate with the hook. Cannot be used with `anyMeetingType`.
`anyMeetingType`	boolean	No	If set to `true`, the hook applies to any meeting type. Is prior to `meetingTypeId`.

Note: You must provide either meetingTypeId or anyMeetingType.

Delete a Hook

This endpoint allows you to delete an existing hook by its id.

curl -X DELETE "http://api.lemcal.com/api/lemcal/hooks/:id" \
     -H "Authorization: Basic $(echo -n 'userId:apiKey' | base64)" \

The above command deletes the specified hook and returns a 204 No Content status code.

HTTP Request

DELETE http://api.lemcal.com/api/lemcal/hooks/:id

Replace :id with the actual ID of the hook you want to delete.

URL Parameters

Parameter	Type	Required	Description
`id`	string	true	The ID of the hook to delete.

Meeting Types

List meeting types

This endpoint retrieves your meeting types.

HTTP Request

curl -X GET "http://api.lemcal.com/api/lemcal/meeting-types" \
     -H "Authorization: Basic $(echo -n 'userId:apiKey' | base64)"

The above command returns JSON structured like this:


[
  {
    "_id": "met_RLejS4uWmhpqi694q",
    "userId": "usr_3k8N8agFoYCPcyivH",
    "name": "Meeting Type 1",
    "description": "A description",
    "meetingLink": "meeting-link-1",
    "type": "default",
    "color": "#EC6181",
    "duration": 30,
    "status": "enabled",
    "privacy": "public",
    "meetingLocations": [
      { "id": "LY5Q8Y6ciZNkgo8Sr", "provider": "googlemeet" }
    ],
    "questions": [
      {
        "id": "8retcc9tCAmuds7Q7",
        "answerType": "text",
        "enabled": false,
        "question": "A question"
      }
    ],
    "roundRobin": {
      "enabled": true,
      "users": [
        { "id": "usr_3k8N8agFoYCPcyivH", "enabled": true, "weight": 1 }
      ],
      "lastCycle": []
    }
  },
]

GET http://api.lemcal.com/api/lemcal/meetingTypes

Response

List of meeting types

Get a meeting type

This endpoint allows you to retrieve a specific meeting type by its id.

HTTP Request

GET http://api.lemcal.com/api/lemcal/meetingTypes/:_id

curl -X GET "http://api.lemcal.com/api/lemcal/meetingTypes/:_id" \
     -H "Authorization: Basic $(echo -n 'userId:apiKey' | base64)" \

The above command returns JSON structured like this:


{
    "_id": "met_RLejS4uWmhpqi694q",
    "userId": "usr_3k8N8agFoYCPcyivH",
    "name": "Meeting Type 1",
    "description": "A description",
    "meetingLink": "meeting-link-1",
    "type": "default",
    "color": "#EC6181",
    "duration": 30,
    "status": "enabled",
    "privacy": "public",
    "meetingLocations": [
        { "id": "LY5Q8Y6ciZNkgo8Sr", "provider": "googlemeet" }
    ],
    "questions": [
        {
        "id": "8retcc9tCAmuds7Q7",
        "answerType": "text",
        "enabled": false,
        "question": "A question"
        }
    ],
    "roundRobin": {
        "enabled": true,
        "users": [
        { "id": "usr_3k8N8agFoYCPcyivH", "enabled": true, "weight": 1 }
        ],
        "lastCycle": []
    }
}

Parameters

Parameter	Type	Required	Description
`_id`	string	Yes	The ID of the meeting type to retrieve.

Structure of a meeting type

Property	Type	Description
id	string	Unique identifier for the meeting type
userId	string	Identifier of the user who created this meeting type
name	string	Name of the meeting type
description	string	Brief description of the meeting type
meetingLink	string	Custom link for scheduling this meeting type
type	string	Type of the meeting (e.g., "default")
color	string	Hex color code associated with this meeting type
duration	number	Duration of the meeting in minutes
status	string	Current status of the meeting type ("enabled", "disabled")
privacy	string	Privacy setting for the meeting type ("public", "private")
meetingLocations	array	List of possible meeting locations/platforms
meetingLocations[].id	string	Unique identifier for the meeting location
meetingLocations[].provider	string	Provider of the meeting platform (e.g., "googlemeet")
questions	array	List of questions to be asked when scheduling
questions[].id	string	Unique identifier for the question
questions[].answerType	string	Type of answer expected (e.g., "text")
questions[].enabled	boolean	Whether the question is currently enabled
questions[].question	string	The actual question text
roundRobin	object	Settings for round-robin scheduling
roundRobin.enabled	boolean	Whether round-robin scheduling is enabled
roundRobin.users	array	List of users participating in round-robin
roundRobin.users[].id	string	Unique identifier of the user
roundRobin.users[].enabled	boolean	Whether the user is active in round-robin
roundRobin.users[].weight	number	Weight assigned to the user in round-robin selection
roundRobin.lastCycle	array	(Not used)

Errors

General Errors

Code	Message	Description
400	Bad Request	The request was invalid or cannot be served.
401	Unauthorized	The request requires user authentication.
404	Not Found	The requested resource could not be found.
405	Method Not Allowed	The request method is known by the server but is not supported by the target resource.

Specific Errors

`/api/lemcal/hooks`

Code	Message	Description
400	You must provide a targetUrl	The `targetUrl` parameter is missing in the request body.
400	Invalid targetUrl	The `targetUrl` provided is not a valid URL.
400	You must provide either a meetingTypeId or anyMeetingType	The request must include either a `meetingTypeId` or `anyMeetingType`.
404	meeting type not found	The provided `meetingTypeId` was not found in the system.
409	Duplicate hook	A hook with the same details already exists.

`/api/lemcal/hooks/:id`

Code	Message	Description
404	hook not found	The specified hook could not be found in the system.