addCardData

Synopsis:

This API request is used to add dynamic card data for the card template. The fields which are set as dynamic on the Card Template are only allowed to be added. The card data is added to the card database and will be used to create the Wallet Card whenever the card generation is triggered. Based on the settings of the Card Template, the card data need to be passed accordingly in the API request and all the other/extra data will be ignored. Additionally, a customer reference ‘customer-ref’, such as a phone number, email address, or customer ID can be passed along with the card data to lock down the card data to the respective entity. That means that this card data will be used to generate a card whenever it is delivered to that phone number (via MMS) or email address (via email). The ‘card-id’ is the identifier from your system to identify the card or card data uniquely and must be passed into the card data. On success, it returns your ‘card-id’ which should be stored and kept in your database along with the data. In the case of relevant-locations, relevant-text is considered only when latitude,longitude values are passed in the API otherwise ignored. For more info see below for Mandatory/Optional fields and Error codes.

Request: JSON

{
	"action" : "addcarddata",
	"api-key" : "API KEY",
	"ct-id" : "CARD TEMPLATE ID",	
	"card-data" : {
		"card-id" : "CUSTOM CARD ID",
		"customer-ref" : "CUSTOMER REFERENCE STRING",		
		"logo-url" : "LOGO IMAGE URL",
		"strip-url" : "STRIP IMAGE URL",
		"thumb-url" : "THUMB IMAGE URL",
		"barcode-value" : "BARCODE VALUE",
		"barcode-text" : "TEXT BELOW BARCODE",
		"header-fields" : [
			{
				"key" : "header-1",
				"label" : "HEADER LABEL",
				"value" : "HEADER VALUE"
			}
		],
		"primary-fields" : [
			{
				"key" : "primary-1",
				"label" : "PRIMARY LABEL",
				"value" : "PRIMARY VALUE"
			},
			{
				"key" : "primary-2",
				"label" : "PRIMARY LABEL",
				"value" : "PRIMARY VALUE"
			}
		],
		"secondary-fields" : [
			{
				"key" : "secondary-1",
				"label" : "SECONDARY LABEL",
				"value" : "SECONDARY VALUE"
			},
			{
				"key" : "secondary-2",
				"label" : "SECONDARY LABEL",
				"value" : "SECONDARY VALUE"
			},
			{
				"key" : "secondary-3",
				"label" : "SECONDARY LABEL",
				"value" : "SECONDARY VALUE"
			},
			{
				"key" : "secondary-4",
				"label" : "SECONDARY LABEL",
				"value" : "SECONDARY VALUE"
			}
		],
		"auxiliary-fields" : [
			{
				"key" : "auxiliary-1",
				"label" : "auxiliary LABEL",
				"value" : "auxiliary VALUE"
			},
			{
				"key" : "auxiliary-2",
				"label" : "auxiliary LABEL",
				"value" : "auxiliary VALUE"
			},
			{
				"key" : "auxiliary-3",
				"label" : "auxiliary LABEL",
				"value" : "auxiliary VALUE"
			},
			{
				"key" : "auxiliary-4",
				"label" : "auxiliary LABEL",
				"value" : "auxiliary VALUE"
			}
		],
		"back-fields" : [
			{
				"key" : "back-1",
				"label" : "BACK LABEL",
				"value" : "BACK VALUE"
			},
			{
				"key" : "back-2",
				"label" : "BACK LABEL",
				"value" : "BACK VALUE"
			},
			{
				"key" : "back-3",
				"label" : "BACK LABEL",
				"value" : "BACK VALUE"
			},
			{
				"key" : "back-4",
				"label" : "BACK LABEL",
				"value" : "BACK VALUE"
			}
		],
		"relevant-locations" : [
			{
				"key" : "relevant-1",
				"latitude" : "CO-ORDINATES",
				"longitude" : "CO-ORDINATES",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "relevant-2,
				"latitude" : "CO-ORDINATES",
				"longitude" : "CO-ORDINATES",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "relevant-3",
				"latitude" : "CO-ORDINATES",
				"longitude" : "CO-ORDINATES",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "relevant-4",
				"latitude" : "CO-ORDINATES",
				"longitude" : "CO-ORDINATES",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "relevant-5",
				"latitude" : "CO-ORDINATES",
				"longitude" : "CO-ORDINATES",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "relevant-6",
				"latitude" : "CO-ORDINATES",
				"longitude" : "CO-ORDINATES",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "relevant-7",
				"latitude" : "CO-ORDINATES",
				"longitude" : "CO-ORDINATES",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "relevant-8",
				"latitude" : "CO-ORDINATES",
				"longitude" : "CO-ORDINATES",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "relevant-9",
				"latitude" : "CO-ORDINATES",
				"longitude" : "CO-ORDINATES",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "relevant-10",
				"latitude" : "CO-ORDINATES",
				"longitude" : "CO-ORDINATES",
				"relevant-text" : "RELEVANCE TEXT"
			}
		],
		"ibeacons" : [
			{
				"key" : "ibeacon-1",
				"proximity-uuid" : "UUID VALUE",
				"major" : "MAJOR VALUE",
				"minor" : "MINOR VALUE",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "ibeacon-2",
				"proximity-uuid" : "UUID VALUE",
				"major" : "MAJOR VALUE",
				"minor" : "MINOR VALUE",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "ibeacon-3",
				"proximity-uuid" : "UUID VALUE",
				"major" : "MAJOR VALUE",
				"minor" : "MINOR VALUE",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "ibeacon-4",
				"proximity-uuid" : "UUID VALUE",
				"major" : "MAJOR VALUE",
				"minor" : "MINOR VALUE",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "ibeacon-5",
				"proximity-uuid" : "UUID VALUE",
				"major" : "MAJOR VALUE",
				"minor" : "MINOR VALUE",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "ibeacon-6",
				"proximity-uuid" : "UUID VALUE",
				"major" : "MAJOR VALUE",
				"minor" : "MINOR VALUE",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "ibeacon-7",
				"proximity-uuid" : "UUID VALUE",
				"major" : "MAJOR VALUE",
				"minor" : "MINOR VALUE",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "ibeacon-8",
				"proximity-uuid" : "UUID VALUE",
				"major" : "MAJOR VALUE",
				"minor" : "MINOR VALUE",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "ibeacon-9",
				"proximity-uuid" : "UUID VALUE",
				"major" : "MAJOR VALUE",
				"minor" : "MINOR VALUE",
				"relevant-text" : "RELEVANCE TEXT"
			},
			{
				"key" : "ibeacon-10",
				"proximity-uuid" : "UUID VALUE",
				"major" : "MAJOR VALUE",
				"minor" : "MINOR VALUE",
				"relevant-text" : "RELEVANCE TEXT"
			}
		]
	}
}

Request Parameters:

Mandatory: 
action - The API Action, 
api-key - The API Key assigned to your account. It's case sensitive, 
ct-id - The card template Id. Case-Sensitive, 
card-id - The custom card id unique per card data. Case-Sensitive, 
barcode-value (if "Barcode = Allowed" && "Barcode Type = Dynamic" && "Barcode Value Source = Dynamic Value" for Card Template otherwise IGNORED)
customer-ref - The customer reference from your system to reference a particular customer. Such as Email, Phone, Other Identifier.
	
Optional: 
logo-url, strip-url, thumb-url,
barcode-text (if "Barcode = Allowed" && "Barcode Alternate Text = Dynamic Text" for Card Template otherwise IGNORED),
header-fields [key, label, value],
primary-fields (1-2) [key, label, value] - if "Card Template Type = Boarding Pass" otherwise primary-2 is IGNORED,	
secondary-fields (1-4) [key, label, value],	
auxiliary-fields (1-4) [key, label, value],		
back-fields (1-4) [key, label, value],		
relevant-locations (1-10) [key, latitude, longitude, relevant-text],	
ibeacons (1-10) [key, proximity-uuid, major, minor, relevant-text]

Response Parameters:

status, ct-id, card-id, error-code, error-message

Request Example: JSON

{
	"action" : "addcarddata",
	"api-key" : "qTFkykO9JTfahCOqJ0V2Wf5Cg1t8iWlZ",
	"ct-id" : "4e292d3765cf46c8a6c8f59e17fcb7715152325a",
	"card-data" : {
		"card-id" : "GM-12345-M",
		"customer-ref" : "16501234123",		
		"thumb-url" : "http://andreas.com/pixs/steve-jobs.png",
		"barcode-value" : "1234578961A",
		"barcode-text" : "PASS-123-457",
		"header-fields" : [
			{
				"key" : "header-1",
				"label" : "SEAT",
				"value" : "1C"
			}
		],
		"primary-fields" : [
			{
				"key" : "primary-1",
				"label" : "Name",
				"value" : "Vikram Muthyala"
			}
		],
		"secondary-fields" : [
			{
				"key" : "secondary-1",
				"label" : "Date",
				"value" : "4th July, 2013"
			},
			{
				"key" : "secondary-2",
				"label" : "Auditorium",
				"value" : "Gold Room"
			},
		]
		"auxiliary-fields" : [
			{
				"key" : "auxiliary-1",
				"label" : "Address",
				"value" : "Hynes Convention Center, Boston MA"
			}
		],
		"back-fields" : [
			{
				"key" : "back-1",
				"label" : "Terms and Conditions",
				"value" : "Valid for 1 person only. Valid ID required if requested."
			},
			{
				"key" : "back-2",
				"label" : "Snacks and Drinks",
				"value" : "Free Drinks and Snacks are available in the main lobby."
			},
			{
				"key" : "back-3",
				"label" : "Take a Survey to win free ticket",
				"value" : "https://www.survey.com/event/12748493fgh/"
			}
		],
		"relevant-locations" : [
			{
				"key" : "relevant-1",
				"latitude" : "42.347888",
				"longitude" : "-71.087903",
				"relevant-text" : "Event at HYNES CONVENTION CENTRE"
			}
		]
	}
}

Response Example: Success

{
	"status" : "Success",
	"ct-id" : "4e292d3765cf46c8a6c8f59e17fcb7715152325a",
	"card-id" : "GM-12345-M"
}

Response Example: Failure

{
	"status" : "Failure",
	"error-code" : "E802",
	"error-message" : "The ct-id value is invalid."
}

General Error Codes:

Code Description
E100 Invalid request. Make a valid request via JSON POST with all the required variables.
E104 Account Authentication Failed.
E105 This account does not have API access.
E107 This account is not allowed to use this action.
E108 Corrupt JSON in the request. $error.
E109 This account does not have API activated.
E112 API call rejected. IP is not white-listed.
E113 API call rejected. Set throughput exceeded for this API action.
E114 API call rejected. Phone number is blacklisted.
E120 This account has reached the API request limit.
E503 Internal error.


Code Description
E801 The ct-id value is required.
E802 The ct-id value is invalid.
E803 The barcode-value is required.
E810 The card-id value is required.
E812 The card-id value is already taken.
E817 The strip-url value is not accepted. It has to be set as Dynamic in the card template.
E818 The strip-url value is invalid. The image cannot be fetched.
E819 The logo-url value is not accepted. It has to be set as Dynamic in the card template.
E820 The logo-url value is invalid. The image cannot be fetched.
E825 The thumb-url value is not accepted. It has to be set as Dynamic in the card template.
E826 The thumb-url value is invalid. The image cannot be fetched.
E829 The customer-ref value is invalid.
E833 This card template is set to send personalized cards and the customer-ref value is required.
E1521 The key name for header-fields is not correct. It should be header-1.
E840 The header-1 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E841 The header-1 value is not accepted. It has to be set as Dynamic in the card template.
E1522 The key name for primary-fields is not correct. It should be primary-1 or primary-2.
E842 The primary-1 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E843 The primary-1 value is not accepted. It has to be set as Dynamic in the card template.
E844 The primary-2 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E845 The primary-2 value is not accepted. It has to be set as Dynamic in the card template.
E1523 The key name for secondary-fields is not correct. It should be from secondary-1 to secondary-4.
E846 The secondary-1 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E847 The secondary-1 value is not accepted. It has to be set as Dynamic in the card template.
E848 The secondary-2 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E849 The secondary-2 value is not accepted. It has to be set as Dynamic in the card template.
E850 The secondary-3 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E851 The secondary-3 value is not accepted. It has to be set as Dynamic in the card template.
E852 The secondary-4 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E853 The secondary-4 value is not accepted. It has to be set as Dynamic in the card template.
E1524 The key name for auxiliary-fields is not correct. It should be from auxiliary-1 to auxiliary-4.
E854 The auxilliary-1 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E855 The auxilliary-1 value is not accepted. It has to be set as Dynamic in the card template.
E856 The auxilliary-2 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E857 The auxilliary-2 value is not accepted. It has to be set as Dynamic in the card template.
E858 The auxilliary-3 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E859 The auxilliary-3 value is not accepted. It has to be set as Dynamic in the card template.
E860 The auxilliary-4 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E861 The auxilliary-4 value is not accepted. It has to be set as Dynamic in the card template.
E1525 The key name for back-fields is not correct. It should be from back-1 to back-4.
E862 The back-1 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E863 The back-1 value is not accepted. It has to be set as Dynamic in the card template.
E864 The back-2 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E865 The back-2 value is not accepted. It has to be set as Dynamic in the card template.
E866 The back-3 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E867 The back-3 value is not accepted. It has to be set as Dynamic in the card template.
E868 The back-4 label is not accepted. The Dynamic Labels, under Advanced tab needs to be set in the card template.
E869 The back-4 value is not accepted. It has to be set as Dynamic in the card template.
E1526 The key name for relevant-locations is not correct. It should be from relevant-1 to relevant-10.
E870 The relevant-1 latitude, longitude and relevant-text values are not accepted. Relevance-Location1 has to be set as Dynamic in the card template.
E871 The relevant-2 latitude, longitude and relevant-text values are not accepted. Relevance-Location2 has to be set as Dynamic in the card template.
E872 The relevant-3 latitude, longitude and relevant-text values are not accepted. Relevance-Location3 has to be set as Dynamic in the card template.
E873 The relevant-4 latitude, longitude and relevant-text values are not accepted. Relevance-Location4 has to be set as Dynamic in the card template.
E874 The relevant-5 latitude, longitude and relevant-text values are not accepted. Relevance-Location5 has to be set as Dynamic in the card template.
E875 The relevant-6 latitude, longitude and relevant-text values are not accepted. Relevance-Location6 has to be set as Dynamic in the card template.
E876 The relevant-7 latitude, longitude and relevant-text values are not accepted. Relevance-Location7 has to be set as Dynamic in the card template.
E877 The relevant-8 latitude, longitude and relevant-text values are not accepted. Relevance-Location8 has to be set as Dynamic in the card template.
E878 The relevant-9 latitude, longitude and relevant-text values are not accepted. Relevance-Location9 has to be set as Dynamic in the card template.
E879 The relevant-10 latitude, longitude and relevant-text values are not accepted. Relevance-Location10 has to be set as Dynamic in the card template.
E880 The relevant-1 latitude value is invalid.
E881 The relevant-2 latitude value is invalid.
E882 The relevant-3 latitude value is invalid.
E883 The relevant-4 latitude value is invalid.
E884 The relevant-5 latitude value is invalid.
E885 The relevant-6 latitude value is invalid.
E886 The relevant-7 latitude value is invalid.
E887 The relevant-8 latitude value is invalid.
E888 The relevant-9 latitude value is invalid.
E889 The relevant-10 latitude value is invalid.
E890 The relevant-1 longitude value is invalid.
E891 The relevant-2 longitude value is invalid.
E892 The relevant-3 longitude value is invalid.
E893 The relevant-4 longitude value is invalid.
E894 The relevant-5 longitude value is invalid.
E895 The relevant-6 longitude value is invalid.
E896 The relevant-7 longitude value is invalid.
E897 The relevant-8 longitude value is invalid.
E898 The relevant-9 longitude value is invalid.
E899 The relevant-10 longitude value is invalid.
E1527 The key name for ibeacons is not correct. It should be from ibeacon-1 to ibeacon-10.
E950 The ibeacon-1 proximity-uuid, major, minor and relevant-text values are not accepted. iBeacon1 has to be set as Dynamic in the card template.
E951 The ibeacon-2 proximity-uuid, major, minor and relevant-text values are not accepted. iBeacon2 has to be set as Dynamic in the card template.
E952 The ibeacon-3 proximity-uuid, major, minor and relevant-text values are not accepted. iBeacon3 has to be set as Dynamic in the card template.
E953 The ibeacon-4 proximity-uuid, major, minor and relevant-text values are not accepted. iBeacon4 has to be set as Dynamic in the card template.
E954 The ibeacon-5 proximity-uuid, major, minor and relevant-text values are not accepted. iBeacon5 has to be set as Dynamic in the card template.
E955 The ibeacon-6 proximity-uuid, major, minor and relevant-text values are not accepted. iBeacon6 has to be set as Dynamic in the card template.
E956 The ibeacon-7 proximity-uuid, major, minor and relevant-text values are not accepted. iBeacon7 has to be set as Dynamic in the card template.
E957 The ibeacon-8 proximity-uuid, major, minor and relevant-text values are not accepted. iBeacon8 has to be set as Dynamic in the card template.
E958 The ibeacon-9 proximity-uuid, major, minor and relevant-text values are not accepted. iBeacon9 has to be set as Dynamic in the card template.
E959 The ibeacon-10 proximity-uuid, major, minor and relevant-text values are not accepted. iBeacon10 has to be set as Dynamic in the card template.
E960 The ibeacon-1 proximity-uuid value is invalid.
E961 The ibeacon-2 proximity-uuid value is invalid.
E962 The ibeacon-3 proximity-uuid value is invalid.
E963 The ibeacon-4 proximity-uuid value is invalid.
E964 The ibeacon-5 proximity-uuid value is invalid.
E965 The ibeacon-6 proximity-uuid value is invalid.
E966 The ibeacon-7 proximity-uuid value is invalid.
E967 The ibeacon-8 proximity-uuid value is invalid.
E968 The ibeacon-9 proximity-uuid value is invalid.
E969 The ibeacon-10 proximity-uuid value is invalid.
E970 The ibeacon-1 major value is invalid.
E971 The ibeacon-2 major value is invalid.
E972 The ibeacon-3 major value is invalid.
E973 The ibeacon-4 major value is invalid.
E974 The ibeacon-5 major value is invalid.
E975 The ibeacon-6 major value is invalid.
E976 The ibeacon-7 major value is invalid.
E977 The ibeacon-8 major value is invalid.
E978 The ibeacon-9 major value is invalid.
E979 The ibeacon-10 major value is invalid.
E980 The ibeacon-1 minor value is invalid.
E981 The ibeacon-2 minor value is invalid.
E982 The ibeacon-3 minor value is invalid.
E983 The ibeacon-4 minor value is invalid.
E984 The ibeacon-5 minor value is invalid.
E985 The ibeacon-6 minor value is invalid.
E986 The ibeacon-7 minor value is invalid.
E987 The ibeacon-8 minor value is invalid.
E988 The ibeacon-9 minor value is invalid.
E989 The ibeacon-10 minor value is invalid.
E990 The ibeacon-1 proximity-uuid value is required.
E991 The ibeacon-2 proximity-uuid value is required.
E992 The ibeacon-3 proximity-uuid value is required.
E993 The ibeacon-4 proximity-uuid value is required.
E994 The ibeacon-5 proximity-uuid value is required.
E995 The ibeacon-6 proximity-uuid value is required.
E996 The ibeacon-7 proximity-uuid value is required.
E997 The ibeacon-8 proximity-uuid value is required.
E998 The ibeacon-9 proximity-uuid value is required.
E999 The ibeacon-10 proximity-uuid value is required.


Key Term Definitions:

Term Description
action This is the name of the function you want to execute with the API.
api-key Random key that is assigned to an account that can be used for authorization instead of USER/CARD. You can find and regenerate this key on the ‘API Settings’ page.
ct-id The unique card template ID used to reference a particular card template.
card-id The identifier from your system to identify the card or card data uniquely.
barcode-text Added text that will be shown below the barcode image on the card.
barcode-value The barcode value or Id that will be encoded into the barcode image on the card.
card-data All the data that goes on the card(Array).
customer-ref The customer reference from your system to reference a particular customer, such as a phone number, email, or customer ID.
logo-url The Logo Image public URL.
strip-url The Strip Image public URL.
thumb-url The Thumbnail public URL.
header-fields The header text appears in the top right hand corner of the pass, next to the logo image. It consists for a label and corresponding data text.
primary-fields Primary fields appear below the logo and header fields. These contain the most important information and are displayed prominently.
secondary-fields Secondary fields are displayed below the primary fields and displayed less prominently.
auxiliary-fields Auxiliary fields are displayed below the secondary fields and a of even lesser prominence.
back-fields The back fields are displayed on the back side of the card.
relevant-locations Relevant locations/text set the notifications to appear on the user’s phone, when they are close to the location set by lat/long.
ibeacons Similar to the relevance locations, iBeacons also display notifications. But instead of the geographical location, iBeacons do so based on the location of a Beacon.