Initial setup & documentation

Generate your API Key: API Documentation

The official interactive documentation is located here: https://dsp.samsungads.com/api/graphql/doc. You can see the documentation by clicking on the Docs link on the right (if the panel is collapsed).

This will open the interactive documentation where you can click on item to see more details.

The API uses GraphQL query language. Find the official documentation on the GraphQL query language on the GraphQL site.

Examples using cURL

cURL is an open source command line tool and library for transferring data with URL syntax.

Upload files

In the example below, simply replace __AUTH_TOKEN__ with your Samsung DSP API Key and __FILE__ with the file path to the file you want to upload.

curl -X POST -H 'Content-Type: multipart/form-data' -F "asset=@__FILE__" 'https://dsp.samsungads.com/api/v2/uploads?auth_token=__AUTH_TOKEN__'

Once successful, you will get this as a response.

Example of a response from the uploads endpoint, when uploading the file 300x250.png

{
  "id": 123456,
  "user_id": 25,
  "asset": {
    "url": "http://cdn.adgrx.com/uploads/M5/FX6t_Q8dotyPsNf2Vvlw/300x250.png"
  },
  "url": "http://cdn.adgrx.com/uploads/M5/FX6t_Q8dotyPsNf2Vvlw/300x250.png",
  "file_name": "300x250.png",
  "content_type": "image/png",
  "file_size": 25919,
  "meta": {
    "width": 300,
    "height": 250
  },
  "created_at": "2021-01-07T23:29:15-05:00",
  "updated_at": "2021-01-07T23:29:15-05:00"
}

The important part is the id, which is the upload ID that you will need to include in the GraphQL query.

Queries (Get Data)

In the example below, replace __AUTH_TOKEN__ with your Samsung DSP API Key and __QUERY_HERE__ with the actual GraphQL query.

curl -X POST -H 'Authorization: Bearer __AUTH_TOKEN__' -H 'Content-Type: application/json' --data '{ "query": "__QUERY_HERE__" }' 'https://dsp.samsungads.com/api/graphql'

CURL example with a file

With cURL, you can also send a file with the data instead of having it all in the command. In the example below, replace __AUTH_TOKEN__ with your Samsung DSP API Key and __FILE_HERE__ with the JSON file.

curl -X POST -H 'Authorization: Bearer __AUTH_TOKEN__' -H 'Content-Type: application/json' -d@__FILE_HERE__ 'https://dsp.samsungads.com/api/graphql'

Creatives

In the example below, replace __CREATIVE_ID__ with your Samsung DSP creative ID or a list of creative IDs, separated by commas.

Each creative type might contains different fields so you can include those fields in an inline fragment.

Image

GraphQL query to get one or multiple creatives data from Samsung DSP

{
  creatives(filter: "id IN (__CREATIVE_ID__)") {
    data {
      name
      type
      ... on CreativesImage {
        adchoices_position
        image_file {
          file_name
        }
      }
      audits {
        audit_type
        state
        latest_feedback
      }
    }
  }
}

Image and video in the same query

GraphQL query to get one or multiple creatives data from Samsung DSP, with fields from the Image creative type and Video creative type.

{
  creatives(filter: "id IN (__CREATIVE_ID_1__,__CREATIVE_ID_2__)") {
    data {
      name
      type
      ... on CreativesVideo {
        adchoices_position
        original_file {
          file_name
        }
      }
      ... on CreativesImage {
        adchoices_position
        image_file {
          file_name
        }
      }
      audits {
        audit_type
        state
        latest_feedback
      }
    }
  }
}

Note that the examples above only show a subset of the available fields for creatives. Please check the interactive documentation for more info on which fields are available (and how to include them in your GraphQL query)

Mutations (Push Data)

Mutation are used when you want to create or update elements.

In cases where you need to upload files, you will need to upload the files first, get their resulting upload id and include that ID in the GraphQL mutation (see Upload files).

Creatives

In the example below, replace __ADVERTISER_ID__ with the advertiser ID, __FORMAT_ID__ with the format ID and __FILE_UPLOAD_ID__ with the upload ID from the output you got when you uploaded the file in the previous step (see Upload files).

Create an image

GraphQL query

mutation CreateImageCreative($creative_obj: SaveCreativesImageInput!){
  create_image_creative(input: $creative_obj) {
    data_with_errors { id errors { full_messages } }
    success
  }
}

GraphQL variables

Here’s the minimal information you need to provide to create an image creatives.

{
  "creative_obj": {
    "name": "My creative name",
    "advertiser_id": __ADVERTISER_ID__,
    "format_id": __FORMAT_ID__,
    "image_file_upload_id": __FILE_UPLOAD_ID__,
    "click_destination_url": "https://www.samsungads.com",
    "declared_destination_url": "https://www.samsungads.com"
  }
}

The image_file_upload_id comes from the output you got when you uploaded the file in the previous step (see Upload files).

Lists

Replace __FILE_UPLOAD_ID__ with the file upload ID comes from the output you got when you uploaded the file in the previous step (see Upload files). Replace __LIST_ID__ with the list ID you want to edit.

Create an IP list

GraphQL query

mutation CreateIPList($list_obj: SaveIplistInput!) {
  create_iplist(input: $list_obj) {
    data {id count}
    errors { has_errors full_messages }
    success
  }
}

GraphQL variables

{
  "list_obj": {
    "name": "My list name",
    "upload_id": __FILE_UPLOAD_ID__,
    "force_deploy": false
  }
}

The upload_id comes from the output you got when you uploaded the file in the previous step (see Upload files).

Update an existing IP list

GraphQL query

mutation UpdateIPList($list_obj: SaveIplistInput!, $list_id: Int!) {
  update_iplist(input: $list_obj, id: $list_id) {
    data {id count}
    errors { has_errors full_messages }
    success
  }
}

GraphQL variables

Here’s the minimal information you need to provide to create an image creatives.

{
  "list_obj": {
    "name": "My list name",
    "upload_id": __FILE_UPLOAD_ID__,
    "force_deploy": false
  },
  "list_id": __LIST_ID__
}

The upload_id comes from the output you got when you uploaded the file in the previous step (see Upload files)

Samsung DSP Standard Segments

Replace __ID__ with the segment ID you want to edit.

Create a segment with an expiry of 15 days

Graph QL query

mutation CreateStandardSegment($input: StandardSegmentInput!) {
  create_standard_segment(input: $input) {
    data {
      id
      name
      ttl
    }
    errors {
      has_errors
      full_messages
    }
    success
  }
}

GraphQL variables

Here’s the minimal information you need to provide to create an image creatives

{
  "input": {
    "name": "My Segment Name",
    "description": "Segment description",
    "ttl": 1296000
  }
}

Update an existing segment

GraphQL query

mutation UpdateStandardSegment($input: StandardSegmentInput!, $id: Int!) {
  update_standard_segment(input: $input, id: $id) {
    data {id name ttl}
    errors { has_errors full_messages }
    success
  }
}

GraphQL variables

Here’s the minimal information you need to provide to create an image creatives.

{
  "input": {
    "name": "My New Segment Name",
    "description": "New Segment description",
    "ttl": 1296000
  },
  "id": __ID__
}

Step by Step example with Smart TV list upload

Create a new Smart TV list

1. Upload your list: Replace __AUTH_TOKEN__ with your Samsung DSP API Key and __FILE__ with the file path to the file you want to upload.

   curl -X POST \
     -H 'Content-Type: multipart/form-data' \
     -F "asset=@my_filename.csv" \
     'https://dsp.samsungads.com/api/v2/uploads?auth_token=__AUTH_TOKEN__'

2. Get the Upload ID from the output
   

   {
     "id": 123456,
     "user_id": 25,
     "asset": {
       "url": "http://cdn.adgrx.com/uploads/M5/FX6t_Q8dotyPsNf2Vvlw/300x250.png"
     },
     "url": "http://cdn.adgrx.com/uploads/M5/FX6t_Q8dotyPsNf2Vvlw/300x250.png",
     "file_name": "300x250.png",
     "content_type": "image/png",
     "file_size": 25919,
     "meta": {
       "width": 300,
       "height": 250
     },
     "created_at": "2021-01-07T23:29:15-05:00",
     "updated_at": "2021-01-07T23:29:15-05:00"
   }

3. Create the new list: Replace __AUTH_TOKEN__ with your Samsung DSP API Key and __FILE_UPLOAD_ID__ with the upload ID from the output you got when you uploaded the file in the previous step
   

   curl -X POST \
     -H 'Authorization: Bearer __AUTH_TOKEN__' \
     -H 'Content-Type: application/json' \
     --data '{ "query": "mutation CreateSTVList($list_obj: SaveStvlistInput!) {create_stvlist(input: $list_obj) {data {id count} errors { has_errors full_messages } success}}", "variables": "{\"list_obj\":{\"name\":\"My Smart TV List\", \"upload_id\":__FILE_UPLOAD_ID__, \"source\":\"samsung_ads\", \"force_deploy\": false, \"use_device_graph\":false}}" }' \
     'https://dsp.samsungads.com/api/graphql'