How to Make API Calls

This page describes the common specifications you should know to use the LINE WORKS APIs.

The LINE WORKS APIs are RESTful you need to use HTTPS to access endpoints.

Authorization {#authorization}

Making an API call requires an access token. To make an API call, specify your access token with Bearer in the Authorization header.

Authorization: Bearer {Access Token}

Caution

• The authorization type must be Bearer. Please make sure to put an empty space between Bearer and the access token.

You can get an access token in two ways. For more information, see Authentication and authorization.

API endpoint {#api-endpoint}

The endpoint (URL) to access when you use the LINE WORKS APIs is as follows:

https://www.worksapis.com/v1.0/...

Example) Get bots using the GET method

GET https://www.worksapis.com/v1.0/bots

HTTP methods {#http-method}

Every API call is made by combining an HTTP method with a URL.
An HTTP method defines what to do after accessing the resource. The LINE WORKS APIs use the following HTTP methods:

• GET: Get a resource
  • It is used for API operations to retrieve data or download files.
• POST: Create a resource
  • It is used for data transfer API operations, such as adding data, sending bot messages, and uploading files.
  • The request content is specified in the request body.
  • An object created using a POST request is usually returned as a response.
• PUT: Update a resource
  • It is used for API operations to edit data.
  • The updated object is usually returned as a response.
  • The response is updated to the values specified in the request body.

  Caution
  • The properties not specified in the request body will be replaced by the default values or will be set to null.

• PATCH: Update part of a resource
  • It is used for API operations to update part of data.
  • The updated object is usually returned as a response.
  • Only the properties specified in the request body are updated; those not specified remain the same.
• DELETE: Delete a resource
  • It is used for API operations to delete data.

Parameter {#request-parameter}

An API operation works differently depending on which parameters are specified. You can specify the following types of parameters to make an API call: "path parameters" that specify a resource, "query parameters" that control how other APIs behave, and a "request body" that specifies the properties of an object.

Caution

• Path parameters and query parameters must be URL-encoded.
• Make sure to use the parameters defined in the API reference. Otherwise, an error or an unintentional operation may occur.

Path parameter {#path-parameter}

To make an API call to access a specific resource, you need to include a path parameter that identifies the resource in the request URL. A path parameter must be specified.
In the API reference, a path parameter is indicated as {parameter}.
Example) An API operation that gets calendars that a specific user can access

GET /v1.0/users/{userId}

In this case, {userId} is one of the following values:

• User ID (userId)
  • Example: userf7da-f82c-4284-13e7-030f3b4c756x
• Email (email)
  • Example: user@domain
• External key (externalKey)
  • Example: externalKey:ExternalKeyValue

Note

• In the API reference, an external key is indicated in the externalKey:{userExternalKey} format.
• Move {userExternalKey} to the actual external key (ExternalKeyValue) and specify it as externalKey:ExternalKeyValue.

The request URL that specifies a user ID is as follows:

GET /v1.0/users/userf7da-f82c-4284-13e7-030f3b4c756x

For values that can be specified for each API operation, see the API reference.

me keyword {#me-keyword}

For some API operations, you can use the me keyword instead of userId in path parameters. The me keyword uses the access token of the authenticated user to make an API call.
Example) If you use userId of the logged-in user, the following two API operations will return the same results.

• GET /v1.0/users/me/calendar
• GET /v1.0/users/{userId}/calendar

Caution

• For JWT authentication tokens with a service account, you cannot use the me keyword.

Query parameter {#query-parameter}

A query parameter is used to specify how the API operation behaves. It is either required or optional. For more information, see the API reference.

• Examples of a query parameter include the number of items to get (count) and a cursor for pagination (cursor).
• To specify a query parameter, add "?" followed by a pair of a parameter name and a value separated by "=" in the request URL. To add multiple query parameters, use &.

Example) An API operation that gets members by specifying a domain (domainId) and the number of members to get (count)

GET /v1.0/users?domainId=10000001&count=20

Request/response body {#request-response-body}

The request information and response format for the POST, PUT, and PATCH methods are formatted as JSON (JavaScript Object Notation), and use the character code, UTF-8. Specify the following Content-Type in the header.

Content-Type: application/json; charset=UTF-8

Note

• Some API operations do not use JSON format. For more information, see the API reference.

JSON format {#json-format}

Here is the summary of JSON format.

In JSON format, an object is enclosed with { and }, containing a property and a value. A property name and a value, separated by :, are enclosed with ". A property and an object are separated by ,.

String {#json-string}

Enclose a string with ".

{   "string" : "String"}

Number {#json-number}

Use a number as is.

{     "number" : 12345}

Boolean/null {#json-bool-and-null}

Use a boolean or null value as lowercase true, false, and null, without enclosing it with ".

{   "bool-true" : true,   "bool-false" : false,   "null" : null}

Nested objects {#json-nest}

Enclose nested objects with { and }.

{   "object" : {     "property1" : "value1",     "property2" : "value2"   }}

Array {#json-array}

Specify an array by enclosing multiple objects or values with [ and ].

{   "ObjectArray" : [     {       "object" : "1st object"     },     {       "object" : "2nd object"     }   ],   "ValueArray" : [     "ValueA",     "ValueB"   ]}

In JSON format, the order of properties or objects has no meaning. So do spaces, tabs, or line breaks. So the following two code examples mean the same thing.

{   "Property1" : 1,   "Property2" : 2}

{"Property2":2,"Property1":1}

HTTP status code {#status-code}

The result of an API request is determined by the HTTP status code included in the response.

If an API call was successful, a status code 2xx indicating success or 3xx indicating redirect is returned.
If an API call failed, on the other hand, the status code 4xx indicating the client's request error or 5xx indicating a server error is returned.

Here is a list of HTTP status codes that is usually returned.

Error code {#error-response}

If an error occurs, check the error code included in the response body.

For more information, see Error Codes.

Pagination {#pagination}

Pagination is a mechanism that separates results returned as a response to an API call into multiple pages.

For more information, see Pagination.

Upload or download files {#file-upload-download}

The LINE WORKS APIs provide API operations to upload or download files. How to upload or download files works the same for each API operation.

For more information, see Upload or Download Files.

Limits {#call-limitation}

The LINE WORKS APIs have "rate limits" and "concurrent request limits" for improved service stability. If the limits are exceeded, an API call temporarily fails.

For more information, see Rate Limits.

Audit logs {#check-api-call}

API calls are recorded in the audit logs of each service. For more information, see Audit in Administrator Guide.

Appendix {#appendix}

For further information, see Appendix.