List

In addition to the standard describe, query, update, and delete calls available for lead database objects, Custom Objects have a list call available. Calling this endpoint will return a response with a list of custom objects available in the destination instance, along with additional metadata about the objects.

Request

1

GET/rest/v1/customobjects.json

Response

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

{

"requestId":"185d6#14b51985ff0",

"success":true,

"result":[

{

"name":"Car",

"displayName":"Car",

"description":"Car owner",

"createdAt":"2015-02-03T22:36:23Z",

"updatedAt":"2015-02-03T22:36:24Z",

"idField":"marketoGUID",

"dedupeFields":["vin"],

"searchableFields":[

["vin"],

["marketoGUID"],

["siebelId"]

],

"relationships":[

{

"field":"siebelId",

"type":"parent",

"relatedTo":{

"name":"Lead",

"field":"siebelId"

}

}

]

}

]

}

The response will give a list of the relationships present on each object. A relationship will have a field member which indicates the field on the object which holds the link value, a type member which indicates if the relationship is to a parent or a child type object, and a relatedTo object indicating the name of the related object, and the link field on that object.

Describe

The describe call for custom objects follows the same pattern as that of Opportunities and Companies, with the addition of the relationships array in the response and a name path parameter in the URI which takes the name of the custom object type to be described. Like the list call, this will list any relationships that are available for this custom object type.

Request

1

GET/rest/v1/customobjects/{name}/describe.json

Response

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

28

29

30

31

32

33

34

35

36

37

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

85

86

87

88

89

90

91

92

93

94

95

96

{

"requestId":"185d6#14b51985ff0",

"success":true,

"result":[

{

"name":"Car",

"displayName":"Car",

"description":"Car owner",

"createdAt":"2015-02-03T22:36:23Z",

"updatedAt":"2015-02-03T22:36:24Z",

"idField":"marketoGUID",

"dedupeFields":["vin"],

"searchableFields":[

["vin"],

["marketoGUID"],

["siebelId"]

],

"relationships":[

{

"field":"siebelId",

"type":"parent",

"object":{

"name":"Lead",

"field":"siebelId"

}

}

],

"fields":[

{

"name":"marketoGUID",

"displayName":"Marketo GUID",

"dataType":"string",

"length":36,

"updateable":false

},

{

"name":"createdAt",

"displayName":"Created At",

"dataType":"datetime",

"updateable":false

},

{

"name":"updatedAt",

"displayName":"Updated At",

"dataType":"datetime",

"updateable":false

},

{

"name":"vin",

"displayName":"VIN",

"description":"Vehicle Identification Number",

"dataType":"string",

"length":36,

"updateable":false

},

{

"name":"siebelId",

"displayName":"External Id",

"description":"External Id",

"dataType":"string",

"length":36,

"updateable":true

},

{

"name":"make",

"displayName":"Make",

"dataType":"string",

"length":36,

"updateable":true

},

{

"name":"model",

"displayName":"Model",

"description":"Vehicle Model",

"dataType":"string",

"length":255,

"updateable":true

},

{

"name":"year",

"displayName":"Year",

"dataType":"integer",

"updateable":true

},

{

"name":"color",

"displayName":"Color",

"description":"Vehicle color",

"dataType":"String",

"length":255,

"updateable":true

}

]

}

]

}

Query

Querying custom objects is slightly different from other Lead Database APIs, and takes name path parameter like describe. For a normal filterType parameters, the query is a simple GET like queries for other types of records, and requires a filterType and filterValues. It will optionally accept fields, batchSize, and nextPageToken parameters.

Alternatively, when querying with compound keys, the API behaves like the Opportunity Roles API, accepting a POST with a JSON body. The JSON body may have the same members as a GET query, except for filterValues. Instead of filter values, there is an input array which takes objects which contain a member named for each of the object type’s dedupeFields.

Request

1

POST/rest/v1/customobjects/{name}.json?_method=GET

Body

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

{

"filterType":"dedupeFields",

"fields":[

"marketoGuid",

"Bedrooms",

"yearBuilt"

],

"input":[

{

"mlsNum":"1962352",

"houseOwnerId":"42645756"

},

{

"mlsNum":"2962352",

"houseOwnerId":"52645756"

},

{

"mlsNum":"3962352",

"houseOwnerId":"62645756"

}

]

}

Response

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

{

"requestId":"e42b#14272d07d78",

"success":true,

"result":[

{

"seq":0,

"marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fa",

"vin":"19UYA31581L000000",

"createdAt":"2015-02-23T18:21:53Z",

"updatedAt":"2015-02-23T18:23:41Z"

},

{

"seq":1,

"marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fb",

"vin":"29UYA31581L000000",

"createdAt":"2015-02-23T18:21:53Z",

"updatedAt":"2015-02-23T18:23:41Z"

},

{

"seq":2,

"marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fc",

"vin":"39UYA31581L000000",

"createdAt":"2015-02-23T18:21:53Z",

"updatedAt":"2015-02-23T18:23:41Z"

}

]

}

Create and Update

To create or update records, custom objects follow the standard pattern for lead database objects, and is largely based on the information available in the description of the object type. In an example car object, there is just one dedupe field, vin. In order to update or create records when using dedupeFields mode, each record in our input array needs to include at least a vin field.

Request

1

POST/rest/v1/customobjects/{name}.json

Body

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

27

{

"action":"updateOnly",

"dedupeBy":"dedupeFields",

"input":[

{

"vin":"19UYA31581L000000",

"siebelId":"f2676861b5fb",

"make":"BMW",

"model":"3-Series 330i",

"year":2003

},

{

"vin":"29UYA31581L000000",

"siebelId":"f2676861b5fc",

"make":"BMW",

"model":"3-Series 330i",

"year":2003

},

{

"vin":"39UYA31581L000000",

"siebelId":"f2676861b5fd",

"make":"BMW",

"model":"3-Series 330i",

"year":2003

}

]

}

Response

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

{

"requestId":"e42b#14272d07d78",

"success":true,

"result":[

{

"seq":0,

"status":"updated",

"marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fb"

},

{

"seq":1,

"status":"created",

"marketoGUID":"cff23271-f996-47d7-984f-f2676861b5fb"

},

{

"seq":2,

"status":"skipped"

"reasons":[

{

"code":"1004",

"message":"Lead not found"

}

]

}

]

}

When performing updates via idField mode, the idField will always be marketoGUID, so each record will always require a marketoGUID field. Remember that idField is only valid for the updateOnly action type, as this field is always system managed. Your response will include the status of each individual record in the result array, and either a marketoGUID or a reasons array depending on whether or not the operation was successful for an individual record.

Delete

Deleting records is very straightforward. Just select your deleteBy mode, either idField or dedupeFields, and include the corresponding fields in each of the records in your input.

Request

1

POST/rest/v1/customobjects/{name}/delete.json

Body

1

2

3

4

5

6

7

8

9

10

11

12

13

14

{

"deleteBy":"dedupeFields",

"input":[

{

"vin":"19UYA31581L000000"

},

{

"vin":"29UYA31581L000000"

},

{

"vin":"39UYA31581L000000"

}

]

}

Response

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

25

26

{

"requestId":"e42b#14272d07d78",

"success":true,

"result":[

{

"seq":0,

"marketoGUID":"dff23271-f996-47d7-984f-f2676861b5fb",

"status":"deleted"

},

{

"seq":1,

"marketoGUID":"da42707c-4dc4-4fc1-9fef-f30a3017240a",

"status":"deleted"

},

{

"seq":2,

"status":"skipped"

"reasons":[

{

"code":"1013",

"message":"Object not found"

}

]

}

]

}

Like updating, your result will contain a status for each individual record, and either a marketoGUID or a reasons array depending on whether the delete was successful.

Latest Blog Posts

Keep up with what's new in the developer world

Important Change to Activity Records in Marketo APIs March 1, 2017 Note: This post will be updated to reflect changes made to activity records returned by the API due to migration to new infrastructure.
With the rollout of Marketo’s next-generation Activity Service beginning in September 2017, we will be unable to enforce the uniqueness or presence of the integer “id” field in activities, data value changes, or lead ... Read More >

Spring 2018 Updates June 29, 2018 In the Spring 2018 release we are releasing new REST APIs, and web tracking privacy enhancements. See the full list of updates below.
REST API
Static List CRUD
Allows users to remotely Create, Read, Update, and Delete Static List Records. Enables management of the entire lifecycle of a static list through REST APIs, including populating and maintaining membership. ... Read More >

Winter 2018 Updates March 2, 2018 In the Winter 2018 release, we are releasing a few enhancements to our APIs. See the full list of updates below.
Asset APIs
Activate/Deactivate Trigger Campaigns
We have added the ability to activate and deactivate trigger campaigns, which can simplify the process of automating your program templates. This is achieved by calling two newly added endpoints: Activate Smart Campaign, Deactivate ... Read More >