Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
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 Getting Started with DFINERY in the User Guide.
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
DFINERY API uses one domain below.
DFINERY provides the following types of APIs:
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.
Please refer to for more details .
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).
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'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
-
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).
After logging in to the DFINERY Console, you can check it by Service Management going to the left menu ( > > ​​). Key information API Token Service Management Key information API Token
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.
Please refer to tab for token-related response codes and common errors and codes.
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
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.
The consent to receive information can be sent without separate settings through the default value. For more information, please refer to the consent to receive status display in the User Guide.
https://openapi.dfinery.ai
DFINERY API domain
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.
access_token: ${your-import-api-token}Authorization: Bearer ${your-export-api-token}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.
If an API call fails, you can get detailed information about the error via the detailed response code.
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 Before You Begin.
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.
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
curl -X GET "https://openapi.dfinery.ai/api/v1/..." \
-H "access_token: ${your-import-api-token}"curl -X GET "https://openapi.dfinery.ai/api/v1/..." \
-H "Authorization: Bearer ${your-export-api-token}"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
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.
200
20000
OK
Request successful
200
40000
BAD_REQUEST
Invalid request
200
40001
VALIDATION_FAILURE
Verification failed
200 OK
{
"status": true,
"code": 20000,
"message": "OK",
"data": null
}200 OK
{
"status": false,
"code": 40001,
"message": "VALIDATION_FAILURE",
"data": null
}200 OK
{
"status": false,
"code": 50000,
"message": "INTERNAL_SERVER_ERROR",
"data": null
}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
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.
For more information about user profile properties, see the List of Standard User Profile Properties.
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
Please refer to the detailed response for more details.
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
Please refer to the detailed response for more details.
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
1,000,000 per minute
POST api/v1/export/event
This is an API that can extract loaded events.
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.
For more information about event properties, see
Please refer to for more details.
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.
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.
POST /api/v1/user-profile
An API that allows you to create and update customer user properties.
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.
curl -L \
-X POST \
-H 'Authorization: Bearer ${your-export-api-token}' \
-H 'Content-Type: application/json' \
'https://openapi.dfinery.ai/api/v1/export/userprofile?service_id=${your-service-id}' \
-d '{
"audience": "nwh3nu",
"properties_condition_type": "exclude",
"properties": [
"df_birth"
]
}'custom_user_datetime,df_gender,df_kakao_ads_optin,df_membership,df_push_ads_optin,df_push_night_ads_optin,df_push_optin,df_sms_ads_optin,df_unified_id,scenario_list_string
,Male,false,,true,false,true,false,ZCUyK5F,"[""1"",""2""]"
,,false,,false,false,false,false,xrx4ib2,null
,,false,,false,false,true,false,BWCExSV,null
,,false,,false,false,false,false,uZFjOE3,nullcurl -L \
-X POST \
-H 'access_token: ${your-import-api-token}' \
-H 'Content-Type: application/json' \
'https://openapi.dfinery.ai/api/v1/identities?service_id=${your-service-id}' \
-d '{
"identity":{
"external_id": "dfn-user-123",
"email": "[email protected]",
"phone_no": "821012345678"
},
"request_datetime":"2024-06-24T06:01:48.501Z"
}
'Content-Type: application/json
access_token: text
{
"status": true,
"code": "20000",
"message": "OK",
"data": true
}curl -i https://openapi.dfinery.ai/api/v1/...
> HTTP/2 200
> x-ratelimit-limit: 1d
> x-ratelimit-remaining: 99999
> x-ratelimit-reset: 1682593200268curl -i https://openapi.dfinery.ai/api/v1/...
> HTTP/2 429
> x-ratelimit-limit: 1d
> x-ratelimit-remaining: 0
> x-ratelimit-reset: 1682640000000Audience ID that includes the user you want to extract. If the value does not exist, extract all users.
kakao_user_id
String
Kakao ID
line_user_id
String
Line ID
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
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
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
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
List of event properties to filter on, if no value exists, extract all event properties
Event Item (Standard, Custom) Properties
curl -L \
-X POST \
-H 'Authorization: Bearer ${your-export-api-token}' \
-H 'Content-Type: application/json' \
'https://openapi.dfinery.ai/api/v1/export/event?service_id=${your-service-id}' \
-d '{
"events": ["df_purchase"],
"events_condition_type": "include",
"properties": ["df_discount", "df_items_df_price"],
"properties_condition_type": "include",
"from_date": "2024-08-25",
"to_date": "2024-08-26"
}' -o results.csv200 OK
custom_012,custom_event_p_boolean,custom_event_p_datetime,custom_event_p_double,custom_event_p_double_list,custom_event_p_long,custom_event_p_long_list,custom_event_p_string_list,df_api_version,df_correction_datetime,df_delivery_charge,df_discount,df_event_datetime,df_event_detail_log_id,df_event_log_id,df_event_name,df_items_custom_012391239128,df_items_custom_item_boolean,df_items_custom_item_datetime,df_items_custom_item_double,df_items_custom_item_double_list,df_items_custom_item_long,df_items_custom_item_long_list,df_items_custom_item_string,df_items_custom_item_string_list,df_items_df_category1,df_items_df_category2,df_items_df_category3,df_items_df_category4,df_items_df_category5,df_items_df_discount,df_items_df_item_id,df_items_df_item_name,df_items_df_price,df_items_df_quantity,df_keyword,df_order_id,df_payment_method,df_server_datetime,df_service_id,df_sharing_channel,df_sign_channel,df_source_type,df_total_purchase_amount,df_total_refund_amount,df_unified_id,sum
,FALSE,,,null,,null,null,1.0.0,2025.1.6 10:35,,,2025.1.6 10:35,1736127307268:1736127306623:cd20207c-bb2a-4abf-a4a9-80804334cf15,1736127307268:1736127306623:cd20207c-bb2a-4abf-a4a9-80804334cf15,df_end_session,,FALSE,,,null,,null,,null,,,,,,,,,,,,,,2025.1.6 10:35,xyroon,,,SDK,,,7jPY23Q,
,FALSE,,,null,,null,null,1.0.0,2025.1.6 10:35,,,2025.1.6 10:35,1736127307268:1736127306638:19c95a76-868b-49bc-a8a5-68058377342f,1736127307268:1736127306638:19c95a76-868b-49bc-a8a5-68058377342f,df_start_session,,FALSE,,,null,,null,,null,,,,,,,,,,,,,,2025.1.6 10:35,xyroon,,,SDK,,,7jPY23Q,
,FALSE,,,null,,null,null,1.0.0,2025.1.6 10:38,,,2025.1.6 10:38,1736127490036:30873a05-62d3-4007-b643-f500a151be24,1736127490036:30873a05-62d3-4007-b643-f500a151be24,df_start_session,,FALSE,,,null,,null,,null,,,,,,,,,,,,,,2025-01-06 10:38:10.036,xyroon,,,SDK,,,vft57Yw,
,FALSE,,,null,,null,null,1.0.0,2025.1.6 10:38,,,2025.1.6 10:38,1736127513890:1d302d2c-e66e-4e7b-ba1d-94299a18c218,1736127513890:1d302d2c-e66e-4e7b-ba1d-94299a18c218,df_start_session,,FALSE,,,null,,null,,null,,,,,,,,,,,,,,2025.1.6 10:38,xyroon,,,SDK,,,vft57Yw,
,FALSE,,,null,,null,null,1.0.0,2025.1.6 10:38,,,2025.1.6 10:38,1736127521375:0ae48e8f-05f5-48aa-acdd-0ce9c1d62631,1736127521375:0ae48e8f-05f5-48aa-acdd-0ce9c1d62631,df_sign_up,,FALSE,,,null,,null,,null,,,,,,,,,,,,,,2025.1.6 10:38,xyroon,,Kakao,SDK,,,vft57Yw,
,FALSE,,,null,,null,null,1.0.0,2025.1.6 10:38,,,2025.1.6 10:38,1736127534688:10ce7ebd-ac54-4bbd-bd75-1e15c3ff92b6,1736127534688:10ce7ebd-ac54-4bbd-bd75-1e15c3ff92b6,df_start_session,,FALSE,,,null,,null,,null,,,,,,,,,,,,,,2025.1.6 10:38,xyroon,,,SDK,,,vft57Yw,
,FALSE,,,null,,null,null,1.0.0,2025.1.6 10:47,,,2025.1.6 10:47,1736128036788:e90f4559-666c-4b04-9f1b-846c55f3b12d,1736128036788:e90f4559-666c-4b04-9f1b-846c55f3b12d,df_start_session,,FALSE,,,null,,null,,null,,,,,,,,,,,,,,2025.1.6 10:47,xyroon,,,SDK,,,vft57Yw,
,FALSE,,,null,,null,null,1.0.0,2025.1.6 10:47,,,2025.1.6 10:47,1736128047673:c62a93ed-4979-4307-b2d5-cbcc3f46578e,1736128047673:c62a93ed-4979-4307-b2d5-cbcc3f46578e,df_start_session,,FALSE,,,null,,null,,null,,,,,,,,,,,,,,2025.1.6 10:47,xyroon,,,SDK,,,vft57Yw,
,FALSE,,,null,,null,null,1.0.0,2025.1.6 10:47,,,2025.1.6 10:47,1736128055767:95d77aa8-0bf2-4967-908b-0ac60987e250,1736128055767:95d77aa8-0bf2-4967-908b-0ac60987e250,df_start_session,,FALSE,,,null,,null,,null,,,,,,,,,,,,,,2025.1.6 10:47,xyroon,,,SDK,,,vft57Yw,
,FALSE,,,null,,null,null,1.0.0,2025.1.6 10:47,,,2025.1.6 10:47,1736128058570:a68f6530-6496-48c1-b6bb-4593d03b140f,1736128058570:a68f6530-6496-48c1-b6bb-4593d03b140f,df_start_session,,FALSE,,,null,,null,,null,,,,,,,,,,,,,,2025.1.6 10:47,xyroon,,,SDK,,,vft57Yw,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
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 Designing Event Taxonomies in the User Guide.
event_log_id
String
Event Identification ID, UUID Format,
xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
event_name
String
Event name
event_datetime
Datetime
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
Please refer to the detailed response for more details .
40402 TOO_MANY_EVENTS
When the number of events exceeds 100 or the number of event items exceeds 100.
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
If successful, you will receive data in CSV format including the header as a response. For more details, please refer to each API documentation.
200 - OK
The request was successfully received by the server.
400 - Bad Request
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
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
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
Please refer to the detailed response for more details.
curl -L \
-X POST \
-H 'access_token: ${your-import-api-token}' \
-H 'Content-Type: application/json' \
'https://openapi.dfinery.ai/api/v1/events?service_id=${your-service-id}' \
-d '{
"common": {
"identity": {
"external_id": "dfn-user-123",
"email": "[email protected]"
}
},
"events": [
{
"event_log_id": "b0c9cf18-f3c0-4879-bb2e-92c65858dabc",
"event_name": "df_login",
"event_datetime": "2024-06-24T06:01:48.501Z",
"event_properties": null,
"event_items": null
},
{
"event_log_id": "464bc021-9c56-481e-8ee8-3bf06de7c418",
"event_name": "df_purchase",
"event_datetime": "2024-06-24T06:42:25.394Z",
"event_properties": {
"df_order_id": "dwtfmoe",
"df_delivery_charge": 1000,
"df_payment_method": "card",
"df_total_purchase_amount": 4000
},
"event_items": [
{
"df_item_id": "1",
"df_item_name": "item1",
"df_price": 3000,
"df_quantity": 1,
"df_discount": 0
}
]
}
]
}'Content-Type: application/json
access_token: ${your-api-token}
{
"status": true,
"code": "20000",
"message": "OK",
"data": true
}Content-Type: application/json
access_token: ${your-api-token}
{
"status": false,
"code": "40402",
"message": "TOO_MANY_EVENTS",
"data": true
}400 BAD REQUEST
{
"result": "fail",
"message": "exceed_date_range_limit"
}500 INTERNAL_SERVER_ERROR
{
"result": "fail",
"message": "unknown_error"
}curl -L \
-X POST \
-H 'access_token: ${your-import-api-token}' \
-H 'Content-Type: application/json' \
'https://openapi.dfinery.ai/api/v1/user-profile?service_id=${your-service-id}' \
-d '{
"identity": {
"external_id": "dfn-user-123"
},
"user_properties": {
"df_gender": "Female"
},
"request_datetime": "2024-05-14T06:05:46.363Z"
}
'Content-Type: application/json
access_token: text
{
"status": true,
"code": "20000",
"message": "OK",
"data": true
}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.
kakao_user_id
String
Kakao ID
line_user_id
String
Line ID
Event occurrence time
Array of Object
Product Information
Object
Event properties
Request Time, ISODate 8601 Format,
2024-06-24T06:42:25.394Z
kakao_user_id
String
Kakao ID
line_user_id
String
Line ID