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 'username:password' | 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 'username:password' | 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 'username:password' | 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 'username:password' | 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.

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.