Twelve operations for building and managing the marketing audiences a narrowcast targets — creating audiences from uploaded user IDs by JSON or by file, click-based and impression-based audiences derived from earlier sends, renaming, deleting, and reading audience data and shared Business Manager audiences. Uploads are asynchronous jobs limited to ten concurrent operations per audience.
---
openapi: 3.0.0
info:
title: LINE Messaging API
version: "0.0.1"
description:
This document describes LINE Messaging API.
servers:
- url: "https://api.line.me"
security:
- Bearer: []
tags:
- name: manage-audience
- name: manage-audience-blob
paths:
"/v2/bot/audienceGroup/upload":
post:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#create-upload-audience-group
tags:
- manage-audience
operationId: createAudienceGroup
description: "Create audience for uploading user IDs (by JSON)"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CreateAudienceGroupRequest"
required: true
responses:
"202":
description: "OK"
content:
"application/json":
schema:
"$ref": "#/components/schemas/CreateAudienceGroupResponse"
example:
audienceGroupId: 1234567890123
createRoute: MESSAGING_API
type: UPLOAD
description: "audienceGroupName_01"
created: 1613698278
permission: READ_WRITE
expireTimestamp: 1629250278
isIfaAudience: false
put:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#update-upload-audience-group
tags:
- manage-audience
operationId: addAudienceToAudienceGroup
description: "Add user IDs or Identifiers for Advertisers (IFAs) to an audience for uploading user IDs (by JSON)"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/AddAudienceToAudienceGroupRequest"
required: true
responses:
"202":
description: "OK"
# empty JSON object
"/v2/bot/audienceGroup/upload/byFile":
post:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#create-upload-audience-group-by-file
servers:
- url: "https://api-data.line.me"
tags:
- manage-audience-blob
operationId: createAudienceForUploadingUserIds
description: "Create audience for uploading user IDs (by file)."
requestBody:
content:
multipart/form-data:
schema:
description: "Request for createAudienceForUploadingUserIds"
type: object
required:
- file
properties:
description:
type: string
maxLength: 120
description: |+
The audience's name. This is case-insensitive, meaning AUDIENCE and audience are considered identical.
Max character limit: 120
isIfaAudience:
type: boolean
description: |+
To specify recipients by IFAs: set `true`.
To specify recipients by user IDs: set `false` or omit isIfaAudience property.
uploadDescription:
type: string
description: |+
The description to register for the job (in `jobs[].description`).
file:
type: string
format: binary
description: |+
A text file with one user ID or IFA entered per line. Specify text/plain as Content-Type. Max file number: 1
Max number: 1,500,000
encoding:
file:
contentType: text/plain
required: true
responses:
"202":
description: "OK"
content:
"application/json":
schema:
$ref: "#/components/schemas/CreateAudienceGroupResponse"
example:
audienceGroupId: 1234567890123
createRoute: MESSAGING_API
type: UPLOAD
description: "audienceGroupName_01"
created: 1613700237
permission: READ_WRITE
expireTimestamp: 1629252237
isIfaAudience: false
put:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#update-upload-audience-group-by-file
servers:
- url: "https://api-data.line.me"
tags:
- manage-audience-blob
operationId: addUserIdsToAudience
description: "Add user IDs or Identifiers for Advertisers (IFAs) to an audience for uploading user IDs (by file)."
requestBody:
required: true
content:
multipart/form-data:
schema:
description: "Request of the addUserIdsToAudience"
type: object
required:
- file
properties:
audienceGroupId:
type: integer
format: int64
description: "The audience ID."
uploadDescription:
type: string
description: "The description to register with the job"
file:
type: string
format: binary
description: |+
A text file with one user ID or IFA entered per line. Specify text/plain as Content-Type. Max file number: 1
Max number: 1,500,000
encoding:
file:
contentType: text/plain
responses:
"202":
description: "OK"
# empty response
"/v2/bot/audienceGroup/click":
post:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#create-click-audience-group
tags:
- manage-audience
operationId: createClickBasedAudienceGroup
description: "Create audience for click-based retargeting"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CreateClickBasedAudienceGroupRequest"
required: true
responses:
"202":
description: "OK"
content:
"application/json":
schema:
"$ref": "#/components/schemas/CreateClickBasedAudienceGroupResponse"
example:
audienceGroupId: 1234567890123
createRoute: MESSAGING_API
type: CLICK
description: "audienceGroupName_01"
created: 1613705240
permission: READ_WRITE
expireTimestamp: 1629257239
isIfaAudience: false
requestId: bb9744f9-47fa-4a29-941e-1234567890ab
clickUrl: https://developers.line.biz/
"/v2/bot/audienceGroup/imp":
post:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#create-imp-audience-group
tags:
- manage-audience
operationId: createImpBasedAudienceGroup
description: "Create audience for impression-based retargeting"
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/CreateImpBasedAudienceGroupRequest"
required: true
responses:
"202":
description: "OK"
content:
"application/json":
schema:
"$ref": "#/components/schemas/CreateImpBasedAudienceGroupResponse"
example:
audienceGroupId: 1234567890123
createRoute: MESSAGING_API
type: IMP
description: "audienceGroupName_01"
created: 1613707097
permission: READ_WRITE
expireTimestamp: 1629259095
isIfaAudience: false
requestId: bb9744f9-47fa-4a29-941e-1234567890ab
"/v2/bot/audienceGroup/{audienceGroupId}/updateDescription":
put:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#set-description-audience-group
tags:
- manage-audience
operationId: updateAudienceGroupDescription
description: "Renames an existing audience."
parameters:
- name: audienceGroupId
in: path
required: true
description: "The audience ID."
schema:
type: integer
format: int64
requestBody:
content:
application/json:
schema:
"$ref": "#/components/schemas/UpdateAudienceGroupDescriptionRequest"
required: true
responses:
"200":
description: "OK"
"/v2/bot/audienceGroup/{audienceGroupId}":
parameters:
- name: audienceGroupId
in: path
required: true
description: "The audience ID."
schema:
type: integer
format: int64
delete:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#delete-audience-group
tags:
- manage-audience
operationId: deleteAudienceGroup
description: "Delete audience"
responses:
"200":
description: "OK"
# an empty JSON object
get:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-audience-group
tags:
- manage-audience
operationId: getAudienceData
description: "Gets audience data."
responses:
"200":
description: "OK"
content:
"application/json":
schema:
"$ref": "#/components/schemas/GetAudienceDataResponse"
examples:
UPLOADING_USER_IDS:
summary: "Example of an audience used for uploading user IDs"
value:
audienceGroup:
audienceGroupId: 1234567890123
createRoute: OA_MANAGER
type: UPLOAD
description: "audienceGroupName_01"
status: READY
audienceCount: 1887
created: 1608617466
permission: READ
isIfaAudience: false
expireTimestamp: 1624342266
jobs:
- audienceGroupJobId: 12345678
audienceGroupId: 1234567890123
description: "audience_list.txt"
type: DIFF_ADD
status: FINISHED
failedType: AUDIENCE_GROUP_AUDIENCE_INSUFFICIENT
audienceCount: 0
created: 1608617472
jobStatus: FINISHED
CLICK_BASED:
summary: "Example of an audience used for click-based retargeting"
value:
audienceGroup:
audienceGroupId: 1234567890987
createRoute: OA_MANAGER
type: CLICK
description: "audienceGroupName_02"
status: IN_PROGRESS
audienceCount: 8619
created: 1611114828
permission: READ
isIfaAudience: false
expireTimestamp: 1626753228
requestId: c10c3d86-f565-...
clickUrl: https://example.com/
jobs: [ ]
APP_EVENTS:
summary: "Example of an audience used for app events"
value:
audienceGroup:
audienceGroupId: 2345678909876
createRoute: AD_MANAGER
type: APP_EVENT
description: "audienceGroupName_03"
status: READY
audienceCount: 8619
created: 1608619802
permission: READ
activated: 1610068515
inactiveTimestamp: 1625620516
isIfaAudience: false
jobs: [ ]
adaccount:
name: Ad Account Name
"400":
description: "Bad request"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: audience group not found
details:
- message: AUDIENCE_GROUP_NOT_FOUND
"/v2/bot/audienceGroup/list":
get:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-audience-groups
tags:
- manage-audience
operationId: getAudienceGroups
description: "Gets data for more than one audience."
parameters:
- name: page
in: query
required: true
schema:
type: integer
format: int64
minimum: 1
description: "The page to return when getting (paginated) results. Must be 1 or higher."
- name: description
in: query
required: false
schema:
type: string
description: |+
The name of the audience(s) to return.
You can search for partial matches.
This is case-insensitive, meaning AUDIENCE and audience are considered identical.
If omitted, the name of the audience(s) will not be used as a search criterion.
- name: status
in: query
required: false
schema:
"$ref": "#/components/schemas/AudienceGroupStatus"
description: |+
The status of the audience(s) to return. If omitted, the status of the audience(s) will not be used as a search criterion.
- name: size
in: query
required: false
schema:
type: integer
format: int64
example: 20
maximum: 40
description: |+
The number of audiences per page. Default: 20
Max: 40
- name: includesExternalPublicGroups
in: query
required: false
schema:
type: boolean
example: true
description: |+
true (default): Get public audiences created in all channels linked to the same bot.
false: Get audiences created in the same channel.
- name: createRoute
in: query
required: false
schema:
"$ref": "#/components/schemas/AudienceGroupCreateRoute"
description: |+
How the audience was created. If omitted, all audiences are included.
`OA_MANAGER`: Return only audiences created with LINE Official Account Manager (opens new window).
`MESSAGING_API`: Return only audiences created with Messaging API.
responses:
"200":
description: "OK"
content:
"application/json":
schema:
"$ref": "#/components/schemas/GetAudienceGroupsResponse"
examples:
TWO_AUDIENCES:
summary: "Example of when there are two audiences that match the specified filter"
value:
audienceGroups:
- audienceGroupId: 1234567890123
createRoute: OA_MANAGER
type: CLICK
description: "audienceGroupName_01"
status: IN_PROGRESS
audienceCount: 8619
created: 1611114828
permission: READ
isIfaAudience: false
expireTimestamp: 1626753228
requestId: c10c3d86-f565-...
clickUrl: https://example.com/
- audienceGroupId: 2345678901234
createRoute: AD_MANAGER
type: APP_EVENT
description: "audienceGroupName_02"
status: READY
audienceCount: 3368
created: 1608619802
permission: READ
activated: 1610068515
inactiveTimestamp: 1625620516
isIfaAudience: false
hasNextPage: false
totalCount: 2
readWriteAudienceGroupTotalCount: 0
size: 40
page: 1
NO_AUDIENCE:
summary: "Example of when there is no audience that matches the specified filter"
value:
audienceGroups: []
hasNextPage: false
totalCount: 0
readWriteAudienceGroupTotalCount: 0
size: 40
page: 1
"/v2/bot/audienceGroup/shared/{audienceGroupId}":
parameters:
- name: audienceGroupId
in: path
required: true
description: "The audience ID."
schema:
type: integer
format: int64
get:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-shared-audience
tags:
- manage-audience
operationId: getSharedAudienceData
description: "Gets audience data."
responses:
"200":
description: "OK"
content:
"application/json":
schema:
"$ref": "#/components/schemas/GetSharedAudienceDataResponse"
examples:
UPLOADING_USER_IDS:
summary: "Example of an audience used for uploading user IDs"
value:
audienceGroup:
audienceGroupId: 1234567890123
createRoute: OA_MANAGER
type: UPLOAD
description: "audienceGroupName_01"
status: READY
audienceCount: 1887
created: 1608617466
permission: READ
isIfaAudience: false
expireTimestamp: 1624342266
jobs:
- audienceGroupJobId: 12345678
audienceGroupId: 1234567890123
description: "audience_list.txt"
type: DIFF_ADD
status: FINISHED
failedType: AUDIENCE_GROUP_AUDIENCE_INSUFFICIENT
audienceCount: 0
created: 1608617472
jobStatus: FINISHED
CLICK_BASED:
summary: "Example of an audience used for click-based retargeting"
value:
audienceGroup:
audienceGroupId: 1234567890987
createRoute: OA_MANAGER
type: CLICK
description: "audienceGroupName_02"
status: IN_PROGRESS
audienceCount: 8619
created: 1611114828
permission: READ
isIfaAudience: false
expireTimestamp: 1626753228
requestId: c10c3d86-f565-...
clickUrl: https://example.com/
jobs: [ ]
APP_EVENTS:
summary: "Example of an audience used for app events"
value:
audienceGroup:
audienceGroupId: 2345678909876
createRoute: AD_MANAGER
type: APP_EVENT
description: "audienceGroupName_03"
status: READY
audienceCount: 8619
created: 1608619802
permission: READ
activated: 1610068515
inactiveTimestamp: 1625620516
isIfaAudience: false
jobs: [ ]
owner:
serviceType: lap
id: A012345678
name: Ad Account Name
"400":
description: "Bad request"
content:
"application/json":
schema:
$ref: "#/components/schemas/ErrorResponse"
example:
message: audience group not found
details:
- message: AUDIENCE_GROUP_NOT_FOUND
"/v2/bot/audienceGroup/shared/list":
get:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#get-shared-audience-list
tags:
- manage-audience
operationId: getSharedAudienceGroups
description: "Gets data for more than one audience, including those shared by the Business Manager."
parameters:
- name: page
in: query
required: true
schema:
type: integer
format: int64
minimum: 1
description: "The page to return when getting (paginated) results. Must be 1 or higher."
- name: description
in: query
required: false
schema:
type: string
description: |+
The name of the audience(s) to return.
You can search for partial matches.
This is case-insensitive, meaning AUDIENCE and audience are considered identical.
If omitted, the name of the audience(s) will not be used as a search criterion.
- name: status
in: query
required: false
schema:
"$ref": "#/components/schemas/AudienceGroupStatus"
description: |+
The status of the audience(s) to return. If omitted, the status of the audience(s) will not be used as a search criterion.
- name: size
in: query
required: false
schema:
type: integer
format: int64
example: 20
maximum: 40
description: |+
The number of audiences per page. Default: 20
Max: 40
- name: createRoute
in: query
required: false
schema:
"$ref": "#/components/schemas/AudienceGroupCreateRoute"
description: |+
How the audience was created. If omitted, all audiences are included.
`OA_MANAGER`: Return only audiences created with LINE Official Account Manager (opens new window).
`MESSAGING_API`: Return only audiences created with Messaging API.
- name: includesOwnedAudienceGroups
in: query
required: false
schema:
type: boolean
default: false
description: |+
true: Include audienceGroups owned by LINE Official Account Manager
false: Respond only audienceGroups shared by Business Manager
responses:
"200":
description: "OK"
content:
"application/json":
schema:
"$ref": "#/components/schemas/GetSharedAudienceGroupsResponse"
examples:
TWO_AUDIENCES:
summary: "Example of when there are two audiences that match the specified filter"
value:
audienceGroups:
- audienceGroupId: 1234567890123
createRoute: OA_MANAGER
type: CLICK
description: "audienceGroupName_01"
status: IN_PROGRESS
audienceCount: 8619
created: 1611114828
permission: READ
isIfaAudience: false
expireTimestamp: 1626753228
requestId: c10c3d86-f565-...
clickUrl: https://example.com/
- audienceGroupId: 2345678901234
createRoute: AD_MANAGER
type: APP_EVENT
description: "audienceGroupName_02"
status: READY
audienceCount: 3368
created: 1608619802
permission: READ
activated: 1610068515
inactiveTimestamp: 1625620516
isIfaAudience: false
hasNextPage: false
totalCount: 2
readWriteAudienceGroupTotalCount: 0
size: 40
page: 1
NO_AUDIENCE:
summary: "Example of when there is no audience that matches the specified filter"
value:
audienceGroups: []
hasNextPage: false
totalCount: 0
readWriteAudienceGroupTotalCount: 0
size: 40
page: 1
components:
securitySchemes:
Bearer:
type: http
scheme: bearer
description: "Channel access token"
schemas:
CreateAudienceGroupRequest:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#create-upload-audience-group
type: object
description: "Create audience for uploading user IDs (by JSON)"
properties:
description:
type: string
description: |+
The audience's name. This is case-insensitive, meaning AUDIENCE and audience are considered identical.
Max character limit: 120
maxLength: 120
isIfaAudience:
type: boolean
description: |+
To specify recipients by IFAs: set true.
To specify recipients by user IDs: set false or omit isIfaAudience property.
uploadDescription:
type: string
description: |+
The description to register for the job (in jobs[].description).
audiences:
type: array
items:
"$ref": "#/components/schemas/Audience"
description: |+
An array of user IDs or IFAs.
Max number: 10,000
maxItems: 10000
Audience:
description: "Audience"
type: object
properties:
id:
type: string
description: "A user ID or IFA. You can specify an empty array."
CreateAudienceGroupResponse:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#create-upload-audience-group
type: object
description: "Create audience for uploading user IDs (by JSON)"
properties:
audienceGroupId:
type: integer
format: int64
description: "The audience ID."
createRoute:
type: string
enum:
- MESSAGING_API
description: |+
How the audience was created.
`MESSAGING_API`: An audience created with Messaging API.
type:
"$ref": "#/components/schemas/AudienceGroupType"
description:
type: string
description: "The audience's name."
created:
type: integer
format: int64
description: "When the audience was created (in UNIX time)."
permission:
type: string
enum:
- READ
- READ_WRITE
description: |+
Audience's update permission. Audiences linked to the same channel will be READ_WRITE.
`READ`: Can use only.
`READ_WRITE`: Can use and update.
expireTimestamp:
type: integer
format: int64
description: |+
Time of audience expiration. Only returned for specific audiences.
isIfaAudience:
type: boolean
description: |+
The value indicating the type of account to be sent, as specified when creating the audience for uploading user IDs. One of:
`true`: Accounts are specified with IFAs.
`false` (default): Accounts are specified with user IDs.
AudienceGroupType:
description: "Audience group type"
type: string
enum:
- UPLOAD
- CLICK
- IMP
- CHAT_TAG
- FRIEND_PATH
- RESERVATION
- APP_EVENT
- VIDEO_VIEW
- WEBTRAFFIC
- IMAGE_CLICK
- RICHMENU_IMP
- RICHMENU_CLICK
- POP_AD_IMP
- TRACKINGTAG_WEBTRAFFIC
AddAudienceToAudienceGroupRequest:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#update-upload-audience-group
type: object
description: "Add user IDs or Identifiers for Advertisers (IFAs) to an audience for uploading user IDs (by JSON)"
properties:
audienceGroupId:
type: integer
format: int64
description: "The audience ID."
uploadDescription:
type: string
description: "The audience's name."
audiences:
description: "An array of up to 10,000 user IDs or IFAs."
type: array
items:
"$ref": "#/components/schemas/Audience"
maxItems: 10000
CreateClickBasedAudienceGroupRequest:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#create-click-audience-group
type: object
description: "Create audience for click-based retargeting"
properties:
description:
type: string
description: |+
The audience's name. This is case-insensitive, meaning AUDIENCE and audience are considered identical.
Max character limit: 120
maxLength: 120
requestId:
type: string
description: |+
The request ID of a broadcast or narrowcast message sent in the past 60 days.
Each Messaging API request has a request ID.
clickUrl:
type: string
format: uri
description: |+
The URL clicked by the user. If empty, users who clicked any URL in the message are added to the list of recipients.
Max character limit: 2,000
maxLength: 2000
CreateClickBasedAudienceGroupResponse:
externalDocs:
url: https://developers.line.biz/en/reference/messaging-api/#create-click-audience-group
type: object
description: "Create audience for click-based retargeting"
properties:
audienceGroupId:
type: integer
format: int64
description: "The audience ID."
type:
"$ref": "#/components/schemas/AudienceGroupType"
description:
type: string
description: "The audience's name."
created:
type: integer
format: int64
description: "When the audience was created (in UNIX time)."
requestId:
type: string
description: "The request ID that was specified when the audience was created."
clickUrl:
type: string
format: uri
description: "The URL that was specified when the audience was created."
createRoute:
type: string
enum:
- MESSAGING_API
description: |+
How the audience was created.
`MESSAGING_API`: An audience created with Messaging API.
permission:
type: string
enum:
- READ
- READ_WRITE
description: |+
Audience's update permission. Audiences linked to the same channel will be READ_WRITE.
- `READ`: Can use only.
- `READ_WRITE`: Can use and update.
expireTimestamp:
type: integer
format: int64
description: "Time of audience expiration. Only returned for specific audiences."
isIfaAudience:
type: boolean
default: false
description: |+
The value indicating the type of account to be sent, as specified when creating the audience for uploading user IDs. One of:
true: Accounts are specified with IFAs.
false (defaul
# --- truncated at 32 KB (44 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/line/refs/heads/main/openapi/line-manage-audience-openapi.yml