How to Make API Calls

Combine an HTTP method with the request URL to complete an operation. For example, here is the operation to send a message. Example) Operation for sending a message

POST https://apis.worksmobile.com/{API ID}/mail/sendMail

You can see a request URL for each API call in the corresponding API details section.

Request Common

With each API call, you should include a LINE WORKS token and a consumer key in the request header. For information on how to get a LINE WORKS token and a consumer key, refer to Preparations. The code below shows how to set your LINE WORKS token and consumer key in the request header.

Caution

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

method.setRequestHeader("consumerKey", "consumer key");
method.setRequestHeader("Authorization", "Bearer token");

Response Common

An error code and message are returned when the API call fails.

Note

Each API returns different response results when the API call succeeds, so refer to the corresponding API details section.

Property	Type	Required	Description
errorCode	String	Y	Error code
errorMessage	String	Y	Error message

The following table shows detailed error codes and messages.

Error code	REST API response code	Error message	Description
001	404	Not support url	The request URL is not supported
002	404	Not support port	The port is not supported
024	401	Authentication failed	API authentication with the consumer key and the token failed
028	401	Authentication header not exists	The consumer key and the token are not included in the request header
029	401	Malformed authentication header	The consumer key and the token in the request header are malformed
041	403	Not allowed tenantApiId	The ClientOpenAPIID is not allowed
042	403	Not allowed consumerKey	The consumer key is not allowed
043	403	Not allowed remote ip	The IP address is not allowed
044	403	Not allowed domainId	The domain ID is not allowed
045	403	Not allowed service	The service is not allowed
051	404	Api not exists	The API does not exist
064	405	Malformed http method	The HTTP method is not supported
065	400	Mandatory parameter not exists	The required parameters are missing
081	400	Target not exists	Target does not exist
083	500	Additional information fail	Failed to get additional information
085	429	Daily quota fail	Daily quota has been exceeded
086	503	Service use fail	Failed to use the service (Mail, Message Bot, etc.)
087	403	Domain stop	The domain is suspended.
088	403	Blacklist	The domain or IP address is blacklisted.
089	400	Malformed json parameter	The parameters are not in JSON format, whereas the contentType is application/json.
090	503	Service fail	Service (Mail, Message Bot, etc.) internal errors Example) {errorMessage=Service fail, HTTP/1.1 400 bad_path(name), errorCode=090}
092	429	API rate limit exceeded	Rate limit has been exceeded.
999	500	Unknown error	Unknown error

The error code and message for each API are described in the corresponding API details section.

Appendix: Code Samples

Service API Sample Codes

You can get a consumer key from the LINE WORKS Developer Console.

/** Request an authorization code. */

var consumerKey = "LQwDde6x8eV4ROOCOdSW";
var url = "https://auth.worksmobile.com/oauth/authorize?client_id=" + consumerKey
               + "&redirect_uri=https://mydomain.com/getToken"
               + "&domain=mydomain.com";

window.open(url, 'authorize' , 'width=600px,height=800px');



/** 
 * https://mydomain.com/getToken
 * Request an access token after getting an authorization code.
 */

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.NameValuePair;
import org.apache.commons.httpclient.methods.PostMethod;

public class ServiceApiTest {

    public void testGetAccessToken() throws Exception {
        String url = "https://auth.worksmobile.com/oauth/token";
        String consumerKey = "LQwDde6x8eV4ROOCOdSW";
        String authorizationCode = "QkJxMFc4ekRnMGdLNjhOMQ==";
        String domain = "mydomain.com";

        PostMethod method = new PostMethod(url);
        NameValuePair[] parameters = new NameValuePair[3];
        parameters[0] = new NameValuePair("client_id", consumerKey);
        parameters[1] = new NameValuePair("code", authorizationCode);
        parameters[2] = new NameValuePair("domain ", domain);
        method.setRequestBody(parameters);

        HttpClient client = new HttpClient();
        client.executeMethod(method);
        String response = method.getResponseBodyAsString();

        System.out.println("response=" + response);
        /* response={"errorCode":"00","expire_in":"604800","refresh_token":"AAAAT/bdZsj81ULzym+URwKwM+OEj69MPhkqDuFiWMRjSZkR+Yk","access_token":"AAAA67h9/36ItvAEea7G8ijrDeCy/22BO5IcP0/KkwZO6unIYET6xkmp3RLW"}
         It is recommended to store the access token extracted from the response. */
    }
}

Server API Sample Codes

You can get a consumer key and a token from the LINE WORKS Developer Console.


/** 
 * Call the Server API.
 */

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.NameValuePair;
import org.apache.commons.httpclient.methods.PostMethod;

public class ServerApiTest {

    public void testServerApi() throws Exception {
        String url = 
                     "https://apis.worksmobile.com/kr1wwTrYrbIot/admin/getDomain";
        String consumerKey = "dz0jtXyXc9Zo953HdjZA";
        String token = "AAAA67h9/36ItvAEea7G8ijrDeCy/22BO5IcP0/KkwZO6unIYET6xkmp3RLWt";

        PostMethod method = new PostMethod(url);
        method.setRequestHeader("consumerKey", consumerKey);
        method.setRequestHeader("Authorization", "Bearer " + token);

        NameValuePair[] parameters = new NameValuePair[1];
        parameters[0] = new NameValuePair("params", "{\"domain\":\"mydomain.com\"}");
        method.setRequestBody(parameters);

        HttpClient client = new HttpClient();
        client.executeMethod(method);
        String response = method.getResponseBodyAsString();

        System.out.println("response=" + response);
    }
}

Concurrent Connection

The maximum number of concurrent connection requests is 5. If it is exceeded, the API call may fail.

Rate Limit

Rate limit is the number of API calls that a user can make within a specific time period.

If the number of API calls exceeds the specified rate limit value, API calls are throttled and fail with the following response:

Error code	REST API response code	Error message	Description
092	429	API rate limit exceeded	Rate limit has been exceeded.

The three services, Message, Contact, and Organization are rate limited, with a different rate limit for each.

Category	Product	Rate Limit
Message	Free	60/min per 1 API
Message	Standard, Advanced, Lite, Basic, Premium	200/min per 1 API
Contact	Standard, Advanced, Lite, Basic, Premium	120/min per 1 API
Organization	Standard, Advanced, Lite, Basic, Premium	1000/min per 1 API Applications below are 600 requests/min ● Add Members ● Modify Members ● Delete Members ● Cancel Membership ● Delete Members ● Delete Members immediately

Note

Before using the Organization API, please see Caution.

When you make an API call to a rate-limited service, such as Message, Contact, and Organization, a response is returned with the following three headers added, indicating the current API calls, remaining API calls and time left until reset.

Header	Description	Unit
RateLimit-Limit	Number of API calls made within the specified time
RateLimit-Remaining	Number of remaining API calls within the specified time
RateLimit-Reset	Time left until reset	Sec.

LINE WORKS Developers