After registering your tracking code, you will be able to use the BowNow API.
The API is designed to be RESTful, returning JSON in the response body and an HTTP response status code indicating an error.

• There is a daily usage limit, please refer to "Usage Restrictions".
• Please note that we cannot provide support for APIs.

This section describes the steps required before calling the API.

1. Obtain credentials from the Change Tracking Code screen
2. Obtain an access token using credentials
3. call the API with a token

1. Obtain credentials from BowNow user screen

Authentication is done on a per tracking code basis.
From the "Settings" - "Configure System" screen in the left menu, select the tracking code name.

The "Tracking ID" and "API Key" in the "Code Information" of the screen transition destination will be the authentication information.

Please handle with caution, as it is possible to create/update/delete lead information using such authentication information.

If there is a possibility that the API key has been compromised, please change the API key; if the API key is changed, the issued access token and refresh token will be deleted.

2. Obtain an access token using credentials

The "Access token issued" endpoint obtains a token.
Since the issued access token has a short expiration time, it is also possible to make the authentication state persistent by calling the "Access token update" endpoint with refresh_token in the same response.

$ curl --location --request POST 'https://api.bownow.jp/v1/auth/token' \
  --header 'Tracking-ID: <Tracking ID>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "api_key": "<API Key>"
  }'

Description of each token

Access Token

Used to maintain authentication status. The validity period is 6 hours.

Refresh Token

Used to renew an access token when it expires. The validity period is one month.

Client Token

Used to maintain login status for multiple clients.

3. Calling the API with a token

The BowNow REST API requires a tracking code ID, client token, and access token.

$ curl --location --request POST 'https://api.bownow.jp/v1/statuses/search' \
  --header 'Tracking-ID: <Tracking ID>' \
  --header 'Client-Token: <Client Token>' \
  --header 'Authorization: Bearer <access token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "ids": [
          1,2,3,4,5
      ]
  }'

The API limits the number of requests within a certain period of time.
If the limit is exceeded, 429 Too Many Request is returned.

Quotas

Quotas are managed on a per-license basis.
Quotas are applied on a plan-by-plan basis as follows

Status code

429 Too Many Requests

Response body

{
    "message": "too_many_requests",
    "description": "The request limit has been exceeded."
}

API call limit per minute

It is managed on a per IP basis for the requesting client.
The rate will be set as follows

Status code

429 Too Many Requests

Response body (returned as string)

Retry later

The API responds with a common error when the request is invalid or an unexpected error occurs. An HTTP response status code is assigned to each error. The message indicates the type of error, the description indicates the error content, and the errors indicates the cause of the error.

Data operations that occur in BowNow can be notified via Webhook. Data (JSON format) is sent via POST to a set URL.

• Up to 10 webhooks can be registered, whether enabled or disabled.
• Lead information update notifications due to form conversions are notified as update events.
• Operations via the API are not subject to Webhook notification.
• Please note that we cannot provide support for webhooks.

This section describes the steps necessary to set up a webhook.

1. Create a webhook from the Configure Webhook screen.

Webhook creation is done on a per tracking code basis.
Create a webhook from the Settings - Configure Webhook screen in the left menu.

2. Receive Webhook Notifications

When an operation that meets the "Conditions for sending notifications" is executed, a POST request is sent from BowNow to the "Target URL" with the details of the operation.
The information received can be used for a variety of purposes, such as linking to Slack, sending via email, or registering in the customer's database and displaying in a list.
For the request body of the POST request sent by BowNow, see "Webhook Notification Contents".

3. Check Webhook notification results

When a Webhook notification is sent, a notification log is registered with BowNow.
From the notification log, you can check whether the notification to the registered "target URL" was successful, and what status code was responded in case of failure.
If you have registered a webhook but have not received any notifications, please check the notification log here.
See "Webhook Notification Log" for details.

Webhook notifications can be sent in three different formats: JSON, for Slack, and for Microsoft Teams.

If you select the JSON format, the entire contents of the notification will be sent in a JSON structure.
If you select for Slack or Microsoft Teams, notifications will be sent according to the format supported by each app's webhook and the language used in the licensed account.
For example, if the language used is English, the notification content will be in English.
Please note that if you select "For Slack" or "For Microsoft Teams", the Batch Registration & Operation(New Registration/Modification/Deletion) of update Lead Information is not available in Conditions for sending notifications.

When notifying Slack, please create data variables on the Slack side and configure message notification settings as follows.
key：text
data-type：text

For details, please refer to Webhook Notification Contents.

This section describes the notification content for each Webhook event.

common item

This section describes the notification items common to all Webhook notifications.

Update Lead Information

You will be notified when lead information is updated.
The notifications are as follows.

JSON format notification items

JSON format notification sample

{
  "event": "bulk",
  "resource_name": "lead",
  "message": "Status bulk update has been executed.",
  "records": [
    {
      "sid": "sid_xxxxxxxxxxxxxxxxxxxx",
      "url": "https://bownow.jp/users/xxxxx/details"
    },
    {
      "sid": "sid_xxxxxxxxxxxxxxxxxxxx",
      "url": "https://bownow.jp/users/xxxxx/details"
    }
  ]
}

Notification items for Slack and Microsoft Teams

Sample postings for Slack and Microsoft Teams

BowNow Webhook

Lead information is updated
Update detail：Register
sid：sid_xxxxxxxxxxxxxxxxxxxx
Lead detail URL：https://bownow.jp/users/xxxxx/details

Notification specifications for Batch Registration & Operation(New Registration/Modification/Deletion)

In the case of batch registration & operation, the data to be updated are notified together in a batch.
The maximum number of records included in a single notification is 1,000.
If the number of data to be updated exceeds 1,000, the notification is divided into 1,000 items each.

Message list

Form conversion

You will be notified when a lead converts a form.
The notifications are as follows.

JSON format notification items

JSON format notification sample

{
    "event": "new_lead_cv",
    "resource_name": "contact",
    "records": [
        {
            "contact_sid": "sid_xxxxxxxxxxxxxxxxxxxx",
            "contact_name": "xxxxxxxxxxx",
            "management_number": "xxxxxxxxxxx"
            "contact_type": "normal_form",
            "lead_sid": "sid_xxxxxxxxxxxxxxxxxxxx",
            "lead_url": "https://bownow.jp/users/xxxxx/details"
        }
    ]
}

Notification items for Slack and Microsoft Teams

Sample postings for Slack and Microsoft Teams

BowNow Webhook

Newly registered lead converted to form
Type：Form
Form ID：sid_xxxxxxxxxxxxxxxxxxxx
Form Name：xxxxxxxxxx
Reference Number：xxxxxxxxxx
Lead sid：sid_xxxxxxxxxxxxxxxxxxxx
Lead detail URL：https://bownow.jp/users/xxxxx/details

The notification log can be viewed for each Webhook registered on the Configure Webhook screen. If the webhook notification fails, the HTTP response status code is displayed.
The notification log shows only the last 10 notifications.
Also, there is no retry function present in the notification. If a timeout (30 seconds) occurs, the HTTP response status code is not displayed.

Send a signature in the request header that the sender of the webhook notification is BowNow. By verifying request headers, replay attacks can be prevented and malicious requests can be repelled.

Request Headers

Verification Method

The request can be verified by calculating the same algorithm used for signature generation.

1. Obtain an API key from the Change tracking code screen.
2. Generate a string to be hashed using the : concatenation.
3. Hashing with the SHA-256 algorithm.
4. Encode to URL-safe Base64 format.
5. Ensure that the generated values match the values in BowNow-Signature.

sample code

header_signature = request.headers["BowNow-Signature"]
header_token = request.headers["BowNow-Request-Token"]
header_timestamp = request.headers["BowNow-Timestamp"]
api_key = "your_api_key"
signature = Digest::SHA256.hexdigest("#{api_key}:#{header_token}:#{header_timestamp}:#{request.body.read}")
encoded_signature = Base64.urlsafe_encode64(signature)
raise "Invalid request" if !(encoded_signature.eql?(header_signature))

Operate access token resources.

Operate lead resources.

Execute lead batch registration.

This section describes the steps required to perform bulk lead registration using the API.

1. Get CSV header
   Request the Get CSV header for batch lead registration to obtain the CSV header for bulk lead registration.
   This CSV header is used to create a CSV for bulk lead registration.
   If you would like to see what values should be set for each item, please log in to BowNow and dunload the sample from the lead batch registration screen.(See manual site for validation of each item)
   
2. Upload batch registration CSV
   Request the created CSV to Batch Lead Registration to start the batch lead registration process.
   This API responds when the bulk lead registration process is accepted, and the actual lead registration process is performed asynchronously.
   
3. Check the progress of the lead batch registration process
   Periodically make requests to Get Batch Lead Registration Status to check the progress of the batch lead registration process.
   Estimated processing time is 20 minutes per 10,000 records.
   Processing time may vary depending on usage conditions. Please note that these are reference values.
   The process is complete when status=completed.
   If has_error=true, an error has occurred in lead registration, refer to step 4 to confirm the error.
   If has_uncreated_corporates=true, there is a company that failed to register, see step 5 to check for unregistered companies.
   
4. Check error details
   Request Get lead batch registration error CSV to get the error CSV and check the error contents.
   
5. Check for unregistered companies
   Request Get CSV of unregistered companies in batch lead to get CSV of unregistered companies and check unregistered companies.
   

*The next batch of lead registrations will not be accepted until the batch of lead registrations currently being processed is completed.
*Error CSV and List of Unregistered Companies CSV will be deleted two months after the registration date.