Confused about how to use v3 of the ticketing API

[ajay1]

Hi all,

I'm not sure if it's just me but I'm finding the v3 documentation really confusing.

I'm trying to make an API request to create a ticket. This page shows the endpoint to call and an example JSON body to send to that endpoint, ie:

{
"property_number": "17",
"property_dropdown": "choice_b",
"property_radio": "option_1",
"property_string": "value",
"property_multiple_checkboxes": "chocolate;strawberry",
"property_checkbox": "false",
"property_date": "1572480000000"
}

I assume these are all custom properties so you can pass what you like here? Do you have to append "property_" to the front of each one or are these just examples?

More importantly, on making the request I get an error:

Some required properties were not set.","correlationId":"xxxxx","context":{"properties":["hs_pipeline_stage"]},"category":"VALIDATION_ERROR"}

The overview page says "When creating a new ticket, you must set the hs_pipeline_stage property." but there is no mention of how to structure the request to include those values and searching the docs returns no results?

So my questions are:

 1. How do a structure a valid request to create a ticket?

 2. Why does this example request not just include all the required properties including correlationId and hs_pipeline_stage so you can just hit that page and get what you need without having to go through all the rest of the docs to fill in the other part of the picture?

Many thanks for any help you can provide.

Adam

[WendyGoh · Accepted solution]

Hey @ajay1,

I'm happy to help shed some lights. Let's work through the query one by one 🙂 

1. Here's a sample structure valid request to create a ticket:

{
  "properties": {
    "hs_pipeline_stage": "1",
    "subject": "this is the ticket name"
  }
}

In which the subject is not mandatory but good to have. 

2. 

I believe we share the following JSON body:

{
"property_number": "17",
"property_dropdown": "choice_b",
"property_radio": "option_1",
"property_string": "value",
"property_multiple_checkboxes": "chocolate;strawberry",
"property_checkbox": "false",
"property_date": "1572480000000"
}

because, it is a sample of the various property field types. I.e. if the property has a field type date, you'd need to format the value to be a timestamp miliseconds example like this - - 1572480000000. Additionally, this doesn't means that you have to append property_ to the front of each property name. Those are the internal value of your property name. (Learn more on where you can get internal value of property here: Manage your properties)

In regards to what's the required properties needed when creating tickets, you can refer to this documentation here: CRM API | Tickets > Under the 'Required properties' section.

[alansp]

Thanks for this clarification. It makes sense now, but that example is really confusing. I thought it was saying I had to reference a property number, instead of a property name now.