All pages
Powered by GitBook
1 of 15

API

Import API

Event

POST: Loading an event

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. Request limits should always be considered when linking.

Query Parameters

Name
Whether required
Type
Explanation

service_id

Essential

String

Service ID

Header

Field name
Whether Required
Type
Value
Explanation

Content-Type

Essential

String

application/json

-

access_token

Essential

String

your-api-token-key

API Authentication Token

Request Body

Field Name
Whether Required
Type
Explanation

common

Essential

Object

Common properties for event loading

events

Essential

Array of Object

Event Information

Common

Field Name
Whether Required
Type
Explanation

identity

Essential

Object

User identifier

Identity

User identifier information. You must enter a value in at least one of the fields below.

Field Name
Whether Required
Type
Explanation

external_id

Select

String

External ID

phone_no

Select

String

Phone Number

email

Select

String

Email

kakao_user_id

Select

String

Kakao ID

line_user_id

Select

String

Line ID

Events

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.

Field Name
Whether required
Type
Explanation

event_log_id

Essential

String

Event Identification ID, UUID Format, xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

event_name

Essential

String

Event name

event_datetime

Essential

Datetime

Event occurrence time

event_items

Select

Array of Object

Product Information

event_properties

Select

Object

Event properties

Event_items

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.

Field Name
Whether Required
Type
Explanation

${your-df-item-property-key}

Select

String, Long, Double, Boolean, Datetime, Array

Pre-registered event item attribute information

Event_properties

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.

Name
Whether required
Type
Explanation

${your-event-property-key}

Select

String, Long, Double, Boolean, Datetime, Array

Pre-registered event attribute information

Example request

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": "dfn@gmail.com"
    }
  },
  "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
        }
      ]
    }
  ]
}'

Example response

Normal response

Content-Type: application/json
access_token: ${your-api-token}
{
  "status": true,
  "code": "20000",
  "message": "OK",
  "data": true
}

Failure response

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.

Content-Type: application/json
access_token: ${your-api-token}
{
  "status": false,
  "code": "40402",
  "message": "TOO_MANY_EVENTS",
  "data": true
}

Identity

POST: Create and update a unified profile

POST /api/v1/identities

An API that allows you to create and update your customer's integrated profile.

Query parameters

Name
Whether required
Type
Explanation

service_id

Essential

String

Service ID

Header

Field name
Whether required
Type
Value
Explanation

Content-Type

Essential

String

application/json

-

access_token

Essential

String

your-api-token-key

API Authentication Token

Request body

Field name
Whether required
Type
Explanation

identity

Essential

Object

Common properties for event loading

request_datetime

Essential

Datetime

Request Time, ISODate 8601 Format, 2024-06-24T06:42:25.394Z

Identity

User identification information. You must enter a value in at least one of the fields below.

Field name
Whether required
Type
Explanation

external_id

Select

String

External ID

phone_no

Select

String

Phone number

email

Select

String

Email

kakao_user_id

Select

String

Kakao ID

line_user_id

Select

String

Line ID

Example request

curl -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": "dfn@gmail.com",
      "phone_no": "821012345678"
   },
   "request_datetime":"2024-06-24T06:01:48.501Z"
  }
 '

Example response

Normal response

Content-Type: application/json
access_token: text
{
  "status": true,
  "code": "20000",
  "message": "OK",
  "data": true
}

Failure response

Please refer to the detailed response for more details.

Profile

Get started

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 Before You Begin.

Use Cases

Set consent information for receiving notifications

You can set the user's consent information values ​​for online and offline channels through the Create and Update User Properties API.

Between 9:00 PM and 8:00 AM, we may send you promotional notifications only if you have given us separate consent to receive them.

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.

POST: Create and update user properties

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. Request limits should always be taken into account when linking.

Query parameters

Name
Whether required
Type
Explanation

service_id

Essential

String

Service ID

Header

Field name
Whether required
Type
Value
Explanation

Content-Type

Essential

String

application/json

-

access_token

Essential

String

your-api-token-key

API Authentication Token

Request body

Field name
Whether required
Type
Explanation

identity

Essential

Object

User identifier

user_properties

Essential

Object

User properties

request_datetime

Essential

Datetime

Request Time, ISODate 8601 Format, 2024-06-24T06:42:25.394Z

Identity

User identifier information. You must enter a value in at least one of the fields below.

Field name
Whether required
Type
Explanation

external_id

Select

String

External ID

phone_no

Select

String

Phone number

email

Select

String

Email

kakao_user_id

Select

String

Kakao ID

line_user_id

Select

String

Line ID

User_properties

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.

Field name
Whether required
Type
Explanation

${your-user-property-key}

Select

String, Long, Double, Boolean, Datetime, Array

Pre-registered user attribute information

Example request

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"
}
 '

Example response

Normal response

Content-Type: application/json
access_token: text
{
  "status": true,
  "code": "20000",
  "message": "OK",
  "data": true
}

Failure response

Please refer to the detailed response for more details.

Detailed response

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.

HTTP response codes

Response Code
Explanation

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.

Detailed response code

If an API call fails, you can get detailed information about the error via the detailed response code.

Response Code
Code
Message
Explanation

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

Example response

20000 OK

200 OK
{
  "status": true,
  "code": 20000,
  "message": "OK",
  "data": null 
}

40001 VALIDATION_FAILURE

200 OK
{
  "status": false,
  "code": 40001,
  "message": "VALIDATION_FAILURE",
  "data": null 
}

50000 INTERNAL_SERVER_ERROR

200 OK
{
  "status": false,
  "code": 50000,
  "message": "INTERNAL_SERVER_ERROR",
  "data": null 
}

Export API

Export

POST: Extracting an event

POST api/v1/export/event

This is an API that can extract loaded events.

Query parameters

Name
Whether required
Type
Explanation

service_id

Essential

String

Service ID

Header

Field name
Whether required
Type
Value
Explanation

Content-Type

Essential

String

application/json

-

Authorization

Essential

String

Bearer your-auth-token

API Authentication Token

Request body

Field name
Whether required
Type
Explanation

events

Select

List of String

List of event names to filter, if no value exists, extract all events

events_condition_type

Essential

String

Filtering operator, supports the following values:

all: The whole event,

include: eventsIncludes only events of

exclude: eventsExcluding events

properties

Select

List of String

List of event properties to filter on, if no value exists, extract all event properties

properties_condition_type

Select

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

Essential

Date

Event search start date,yyyy-MM-dd, 2024-12-05

to_date

Select

Date

Event search end date,yyyy-MM-dd, 2024-12-05

Response

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 Designing an Event Taxonomy.

Field name
Division
Explanation

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

Example request

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.csv

Example response

Success response

200 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,

Failure response

Please refer to the detailed response for more details.

POST: Extract user profile

POST api/v1/export/userprofile

This is an API that can extract loaded user profiles.

Query parameters

Name
Whether required
Type
Explanation

service_id

Essential

String

Service ID

Header

Field name
Whether required
Type
Value
Explanation

Content-Type

Essential

String

application/json

-

Authorization

Essential

String

Bearer your-auth-token

API Authentication Token

Request body

Field name
Whether required
Type
Explanation

properties

Select

List of String

List of user attribute names to filter on, if no value exists, extract all user attributes

properties_condition_type

Essential

String

Filtering operator, supports the following values:

all: All user properties,

include: propertiesContains only user properties of

exclude: propertiesExcluding user properties of

audience

Select

String

Audience ID that includes the user you want to extract. If the value does not exist, extract all users.

Response

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.

Field name
Division
Explanation

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

Example request

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"
    ]
}'

Example response

Success response

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,null

Failure response

Please refer to the detailed response for more details.

Detailed response

DFINERY Export API determines the success or failure of a request through HTTP response code and detailed response code.

HTTP response codes

Response Code
Explanation

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.

Detailed response

If an API call fails, you can get detailed information about the error through the detailed response result.

Response Code
Result
Message
Explanation

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.

Example response

Success

If successful, you will receive data in CSV format including the header as a response. For more details, please refer to each API documentation.

exceed_date_range_limit

400 BAD REQUEST
{
    "result": "fail",
    "message": "exceed_date_range_limit"
}

unknown_error

500 INTERNAL_SERVER_ERROR
{
    "result": "fail",
    "message": "unknown_error"
}