Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
You can send events and properties of online/offline users and extract data through DFINERY's API.
Before using DFINERY's API, the following must be prepared in advance.
DFINERY API uses one domain below.
https://openapi.dfinery.ai
DFINERY API domain
DFINERY provides the following types of APIs:
You can load user event data.
Update user identification information. This allows us to identify and integrate users.
You can update user properties.
You can extract user event and behavior data loaded in DFINERY.
DFINERY API uses consistent data types and formats. When users connect to the API, they must make requests that match the data types required by the API.
DFINERY uses API tokens to determine whether a request sent by a user is an authenticated request. All API requests must include an API token in the header. API tokens can be issued through the DFINERY console.
DFINERY's API tokens are divided into Import API and Export API tokens. Import API tokens are used when sending customer data to DFINERY (Event, Identity, Profile API). Export API tokens are used when customers extract data loaded in DFINERY (Export API).
Sign up and create an organization and service : To use the API, you must sign up and create an organization and service. For more information, refer to
Registering Events and User Attributes : DFINERY only loads pre-registered event and user attribute data. If there are any events and user attribute data that you want to load, you must register them in advance in the console. For more information, refer to
API Token Issuance : DFINERY uses API tokens to determine whether a request sent by a user is an authenticated request. API tokens can be issued through the DFINERY Console. For more information, see
Consider API request limits : DFINERY limits the number of API calls per hour for each service. When making API requests, you should design your requests to take API request limits into account. For more information, see
Please refer to for more details .
Please refer to for more details .
DFINERY limits the number of API requests per hour for each service to ensure stable service operation. If the API request limit is exceeded, all subsequent requests will fail, and after the time limit has elapsed and the request limit is reset, the request will succeed. For more information about API request limits, see
DFINERY Import API determines the success or failure of a request through HTTP response code and detailed response code. Even if the HTTP response code is 200, the request may fail.
200 - OK
The request was successfully received by the server.
400 - Bad Request
The request could not be processed. This is the response returned when a required parameter was not sent or the parameter format is incorrect. Please check the request parameters.
429 - Too Many Requests
An unusually high number of requests have been sent. Please try again later.
500 - Server Error
An error occurred inside the server.
If an API call fails, you can get detailed information about the error via the detailed response code.
200
20000
OK
Request successful
200
40000
BAD_REQUEST
Invalid request
200
40001
VALIDATION_FAILURE
Verification failed
200
40101
INVALID_SERVICE_ID
Invalid service ID
200
40201
INVALID_TOKEN
Invalid token provided
200
40401
TOO_MANY_REQUEST
API usage limit exceeded
200
40402
TOO_MANY_EVENTS
Number of events in request exceeded
200
40403
TOO_MANY_USER_PROFILES
Exceeded number of user profiles in a single request
200
50000
INTERNAL_SERVER_ERROR
An internal server error occurred
You can set the user's consent information values for online and offline channels through the Create and Update User Properties API.
User profiles for consent to receive notifications are automatically registered when creating a service in DFINERY, so they can be set up without having to set them in the DFINERY console.
POST /api/v1/events
You can load one or more events at once via the event loading API. The events you want to load must have been registered in advance in the console.
You can load up to 100 events in one request. Also, you can load up to 100 event items in one request.
service_id
String
Service ID
Content-Type
String
application/json
-
access_token
String
your-api-token-key
API Authentication Token
Object
Common properties for event loading
Array of Object
Event Information
Object
User identifier
User identifier information. You must enter a value in at least one of the fields below.
external_id
String
External ID
phone_no
String
Phone Number
email
String
kakao_user_id
String
Kakao ID
line_user_id
String
Line ID
event_log_id
String
Event Identification ID, UUID Format,
xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
event_name
String
Event name
event_datetime
Datetime
Event occurrence time
Array of Object
Product Information
Object
Event properties
This is an event item attribute. The field name should be the sub-attribute name of the item pre-registered in the console (df_item), and the value should be the value of the corresponding attribute. Up to 100 event items can be loaded at a time.
${your-df-item-property-key}
String, Long, Double, Boolean, Datetime, Array
Pre-registered event item attribute information
This is an event attribute. The field name must be the attribute name of an event attribute pre-registered in the console, excluding items ( df_item), and the value must be the value of the attribute.
${your-event-property-key}
String, Long, Double, Boolean, Datetime, Array
Pre-registered event attribute information
40402 TOO_MANY_EVENTS
When the number of events exceeds 100 or the number of event items exceeds 100.
POST /api/v1/identities
An API that allows you to create and update your customer's integrated profile.
service_id
String
Service ID
Content-Type
String
application/json
-
access_token
String
your-api-token-key
API Authentication Token
identity
Object
Common properties for event loading
request_datetime
Datetime
Request Time, ISODate 8601 Format,
2024-06-24T06:42:25.394Z
User identification information. You must enter a value in at least one of the fields below.
external_id
String
External ID
phone_no
String
Phone number
email
String
kakao_user_id
String
Kakao ID
line_user_id
String
Line ID
POST /api/v1/user-profile
An API that allows you to create and update customer user properties.
service_id
String
Service ID
Content-Type
String
application/json
-
access_token
String
your-api-token-key
API Authentication Token
Object
User identifier
Object
User properties
request_datetime
Datetime
Request Time, ISODate 8601 Format,
2024-06-24T06:42:25.394Z
User identifier information. You must enter a value in at least one of the fields below.
external_id
String
External ID
phone_no
String
Phone number
email
String
kakao_user_id
String
Kakao ID
line_user_id
String
Line ID
This is a user property. The field name should be the name of a user property pre-registered in the console, and the value should be the value of that property.
${your-user-property-key}
String, Long, Double, Boolean, Datetime, Array
Pre-registered user attribute information
POST api/v1/export/event
This is an API that can extract loaded events.
service_id
String
Service ID
Content-Type
String
application/json
-
Authorization
String
Bearer your-auth-token
API Authentication Token
events
List of String
List of event names to filter, if no value exists, extract all events
events_condition_type
String
Filtering operator, supports the following values:
all: The whole event,
include: eventsIncludes only events of
exclude: eventsExcluding events
properties
List of String
List of event properties to filter on, if no value exists, extract all event properties
properties_condition_type
String
Filtering operator, supports the following values:
If the value does not exist: the entire event property,
all: All event properties,
include: propertiesContains only the event properties of
exclude: propertiesExcluding event properties
from_date
Date
Event search start date,yyyy-MM-dd, 2024-12-05
to_date
Date
Event search end date,yyyy-MM-dd, 2024-12-05
The response from the event extraction ,is in CSV format with a header separated by. The first line is the header, and the extracted data is from the second line. The table below describes the main headers.
For the Unified ID and System Event properties properties, properties_condition_typethey are always included in the response, regardless of.
If no value exists, the default value is empty.
df_unified_id
Integrated ID
Integrated ID
${your-standard-event-property-key}
Standard event properties
Standard event properties
${your-custom-event-property-key}
Custom event properties
Custom event properties
${your-df-item-property-key}
Standard and custom event properties
Event Item (Standard, Custom) Properties
df_api_version
System Event Properties
Event API Version
event_name
System Event Properties
Event name
df_server_datetime
System Event Properties
Event log server arrival time
df_correction_datetime
System Event Properties
Event occurrence time
df_event_detail_log_id
System Event Properties
Event log ID, if the purchase event contains multiple items,
${df_event_log_id}:${n}It is in the form of.
df_event_log_id
System Event Properties
Event Log ID
You can create or update user properties through the Profile API. To connect to the API, you must first complete the basic settings. If you have not yet completed the basic settings for connecting to the API, please refer to
The consent to receive information can be sent without separate settings through the default value. For more information, please refer to
If you need to load many events, it is better to collect multiple events and call the event loading API at once rather than calling the event loading API individually, in terms of speed and request limits. should always be considered when linking.
This is the event information. The event you want to load must be pre-registered in the console. For more information about standard events and event properties, see
Please refer to for more details .
Please refer to for more details.
It is recommended that API calls for creating and updating user properties be made only when the user's properties change. should always be taken into account when linking.
Please refer to for more details.
For more information about event properties, see
Please refer to for more details.
DFINERY's API uses the data types below. When users connect to the API, they must make a request according to the data type required by the API.
String
-
"foo"
Long
-
1
Double
-
1.0
Boolean
-
true
Array of String
-
["foo", "bar"]
Array of Long
-
[0, 1]
Array of Double
-
[0.0, 1.0]
Datetime
yyyy-MM-dd'T'HH:mm:ss(.SSS)Z
2023-08-15T12:30:00.000Z, 2023-08-15T12:30:00Z,
Date
yyyy-MM-dd
2023-08-15
Request limit refers to the limit on the number of API calls per unit of time. DFINERY applies the request limit policy to all Open APIs it provides to ensure stable service operation.
1,000,000 per minute
10,000 per minute
10,000 per minute
100 cases per hour, 5 cases at the same time
If the request limit is exceeded, all subsequent API requests will fail. After the time limit has elapsed and the request limit is reset, you can receive a normal response. It is recommended to consider the request limit when linking APIs.
Request limit status can be checked through the value of the response header.
X-Rate-Limit-Limit
Initialization cycle
X-Rate-Limit-Remaining
Number of requests remaining
X-Rate-Limit-Reset
Time for the transmission speed to be initialized
DFINERY uses API tokens to determine whether a request sent by a user is an authenticated request. All API requests must include an API token in the header. API tokens can be issued through the DFINERY console.
DFINERY's API tokens are divided into Import API and Export API tokens. Import API tokens are mainly used when sending customer data to DFINERY (Event, Identity, Profile API). Export API tokens are mainly used when customers extract data loaded into DFINERY (Export API).
Import API tokens access_tokencan be used by adding a value to the request header.
Emport API tokens Authorizationcan be used by adding a value to the request header.
DFINERY can only issue one API token per service. If you want to change the token, you can do so by clicking the reissue button (Service Management > Key information > API Token > Reissue).
When reissued, the existing token can only be used for 2 weeks. Please change to a reissued token within 2 weeks.
DFINERY Export API determines the success or failure of a request through HTTP response code and detailed response code.
200 - OK
The request was successfully received by the server.
400 - Bad Request
The request could not be processed. This is the response returned when a required parameter was not sent or the parameter format is incorrect. Please check the request parameters.
429 - Too Many Requests
An unusually high number of requests have been sent. Please try again later.
500 - Server Error
An error occurred inside the server.
If an API call fails, you can get detailed information about the error through the detailed response result.
200
fail
client_connection_closed
The client connection was terminated.
400
fail
invalid_parameter
The requested parameters provided are invalid or malformed.
400
fail
exceed_date_range_limit
The requested start date exceeds the allowed range.
401
fail
unauthorized_token
Invalid Export token.
429
fail
too_many_api_requests
The number of requested API calls exceeded the limit.
500
fail
unknown_error
An unexpected error occurred within the system.
500
fail
query_error
The requested database query failed and was not executed.
POST api/v1/export/userprofile
This is an API that can extract loaded user profiles.
service_id
String
Service ID
Content-Type
String
application/json
-
Authorization
String
Bearer your-auth-token
API Authentication Token
properties
List of String
List of user attribute names to filter on, if no value exists, extract all user attributes
properties_condition_type
String
Filtering operator, supports the following values:
all: All user properties,
include: propertiesContains only user properties of
exclude: propertiesExcluding user properties of
audience
String
Audience ID that includes the user you want to extract. If the value does not exist, extract all users.
The response from the user profile extraction ,is in CSV format with a header separated by. The first line is the header, and the extracted data is from the second line. The table below describes the main headers.
For the unified ID properties, properties_condition_typeit is always included in the response, regardless.
df_unified_id
Integrated ID
Integrated ID
${your-standard-user-property-key}
Standard User Profile Properties
Standard User Profile Properties
${your-custom-user-property-key}
Custom User Profile Properties
Custom User Profile Properties
You can use DFINERY Import API to transfer various offline data to DFINERY server.
The user consented to receive marketing communications after signing up through an offline store. The user then made a purchase at an offline store.
you can check it by Service Management going to the left menu ( > > ). Key information API Token Service Management Key information API Token
Please refer to tab for token-related response codes and common errors and codes.
If successful, you will receive data in CSV format including the header as a response. For more details, please refer to each
For more information about user profile properties, see
Please refer to for more details.
The best practices below assume that you have completed the basic setup for API integration. If you have not yet completed the basic setup for API integration, please refer to
When signing up through an offline store, a new user profile is created via
After signing up, if the user consents to receive marketing, the user's marketing consent properties are updated through
Afterwards, when purchasing at an offline store, the purchase event of the user is loaded through