Common tips for using the APIs

This topic contains tips to help you use the Responsys Web Services API more effectively.

Data management tips

Create a data dictionary

Get to know your data! Create a data dictionary of Profile Lists and PETs. Include the field name, field type, description, and sample values.

Observe field naming requirements

When naming fields in the Profile Lists, Profile Extension Tables, and Supplemental Tables, observe the following guidelines:

  • Must be 30 or fewer characters in length.
  • Permitted characters: A-Z a-z 0-9 , $, # and _ (underscore). Name must start with A-Z a-z.

CAUTION: All system-defined field names are reserved and end with an underscore character. Example: EMAIL_ADDRESS_. Therefore, to avoid duplication, imported custom field names should not end with an underscore. See System-Defined List Fields to review these fields and details.

  • Field names cannot contain the single letters A, E, G, K, M P, T and U. These are reserved by the application.
  • Field names containing at least two characters are recommended.
  • Field names are not case-sensitive, for example: FirstName is the same as firstname.

Do not use reserved Oracle Responsys field name words

CAUTION: To avoid conflicts with the database used by Oracle Responsys, do not use any of the following reserved words as field names in Profile Lists, Profile Extension Tables, and Supplemental Tables.

                   

access

add

admin

administrator

advisor

all

alter

and

any

as

asc

audit

baseurl

between

by

byte

char

check

cluster

column

comment

connect

compress

create

current

data

date

decimal

default

delete

desc

distinct

double

drop

else

exclusive

exists

extends

false

file

first

float

for

from

grant

group

having

ID

identified

if

immediate

import

in

increment

index

initial

insert

int

integer

intersect

into

is

last

level

like

lock

long

M

maxextents

minextents

minus

mlslabel

mode

modify

noaudit

nocompress

nologging

not

nowait

null

number

of

offline

on

online

option

or

order

package

pctfree

pctused

prior

private

privileges

program

protected

public

raw

rename

resource

revoke

row

rowid

rownum

rows

select

session

set

share

size

smallint

start

successful

synonym

sysdate

table

test

then

to

trigger

true

uid

union

unique

update

user

validate

values

varchar

varchar2

view

whenever

where

with

 

 

 

 

 

 

Use available field data types

The following data types are available for all system- and custom-defined fields.

Data Type

Details

Text
(up to 500 chars)

Data type of a field unless you specify otherwise

Long Text
(up to 4000 chars)

Does not use excessive space – Only stores text that is actually present. This limit applies to single-byte character sets, such as English. The limit is lower for multi-byte character sets, such as those used in Asian languages or UTF-8 characters.

Number

Number that may include a decimal

Integer

Whole number with no fractional part. Accommodates values from – 2,147,483,648 through 2,147,483,647

Timestamp
(date + time)

Used by Oracle Responsys for internal purposes.
Format must be yyyy-mm-dd hh:mm:ss

Character encoding tips

Know when to use character encoding:

  • REST API supports UTF-8 character encoding only.
  • To pass extended/accented characters in optionalData payload, they must be escaped as Unicode characters. For example, the euro symbol € is escaped as \u20AC, the yen symbol ¥ is escaped as \u00A5, an ü is escaped as \u00FC, an é is escaped as \u00E9, and the like. Otherwise, you may receive an INVALID_REQUEST_CONTENT error.

Content Library tips

To obtain the path name of a document or folder, you can ask the Responsys Account Administrator to copy it for you from the Content Library in Responsys. The Responsys Account Admin can copy the document path as follows:

  1. Log in to Responsys. From the navigation menu, choose Content, and then choose Manage Content.
  2. Browse to the folder containing the desired document file in the content library.
  3. Hover your mouse over the document file name, and then click the arrow. A drop-down menu is displayed.
  4. Choose Copy filename and path. A dialog is displayed, containing the filename and path.

Screen shot of the menu for a Content Library object

  1. Press Ctrl+c to copy the selected path, and then press the Enter key to close the dialog box.

Screenshot of the content library path to a Content Library object

  1. Paste the path into the desired location (email, text file, or the like).

Authentication tips

When authenticating with the API endpoints, it's best practice to generate an authentication token and refresh the token before it expires. Using a new login for every request is not recommended. For more information, see Refreshing Tokens.

[tips]

Learn more

REST-specific tips

SOAP-specific tips