Base URL
Use the following as the base URL for each API endpoint: https://api.hona.com/partner/v2
Authentication
All API requests must be authenticated with a bearer token included in the request headers.
To obtain a bearer token, follow these steps:
In the Company App, Navigate to
Company Setting→Integrations(https://app.hona.com/company/settings/integrations)Click the
View Detailsbutton on theHonacard.Copy the displayed token or generate a token as needed.
To authenticate each request, include an Authorization header with the value Bearer {token}. Replace {token} with the value that you just copied from Hona.
Example authorization header:
Authorization: Bearer {token}
Contacts
Create or Update Contact
To create a or Update a contact, make a PUT request to the following endpoint:
PUT /contacts (<https://api.hona.com/partner/v2/contacts>)
Request Body
The request body should be a JSON object with the following fields:
externalId: a string representing a unique identifier for the contact in your system used to update the contact in future requests (required)firstName: a string representing the full name of the contact (required)lastName: a string representing the full name of the contact (required)email: a string representing the email address of the contact (required if no phone is provided)phone: a string representing a mobile/text enabled phone number of the contact in the E.164 format (required if no email is provided)
Example request body:
{ "externalId": "123-3123-123", "firstName": "John", "lastName": "Doe", "email": "[email protected]", "phone": "+15551234567" }Response
Status Codes:
201 Created- Successfully created200 Ok- Successfully Updated
Payload:
{ "id": 1, "externalId": "123-3123-123" "firstName": "John", "lastName": "Doe", "email": "[email protected]", "phone": "+15551234567" }Projects
Create or Update Project
To create a new project, make a PUT request to the following endpoint:
PUT /projects (<https://api.hona.com/partner/v2/projects>)
Request Body
The request body should be a JSON object with the following fields:
externalId: a string representing a unique identifier for the project in your system used to update the project in future requests (required)name: a string representing the name of the project (required)partnerPhaseName: a string representing the name of the phase the project is in (required)clients: an array of contact IDs for the clients associated with the project (required)Only 1 client is supported. Adding multiples clients to a single project is currently a work in progress.
partnerProjectTypeName: a string representing the type of project (required)milestonesEnabled: a boolean indicating if milestones are enabled for this project (required)When milestones are disabled then we will not send automatic notifications to the client on the project
status: a string representing the status of the project. Should be one of "Not Started", "In Progress", or "Completed" (required)
Example request body:
{ "projectId": "123-3123-123", "text": "New Project", "authorId": "32435", "clients": [{externalId: "123-1231"}], "partnerProjectTypeName": "Web Dev", "milestonesEnabled": true, "status": "Not Started" }Response
Status Codes:
201 Created- Successfully created200 Ok- Successfully Updated
Payload:
{ "id": 1, "externalId": "123-3123-123", "name": "New Project", "phaseStep": 0 "clients": [{id: 1, externalId: "123-1231", firstName: "", lastName: "", email: "", phone: ""}], "projectType": {id: 1, name: "Web Dev"}, "milestonesEnabled": true, "status": "Not Started" }Messages
Send a Message
To Send a Message, make a POST request to the following endpoint:
POST /send-message (<https://api.hona.com/partner/v2/send-message>)
Request Body
The request body should be a JSON object with the following fields:
text: a string representing the SMS message to be sent to the recipient (required)projectId: This is the id of the object in your case management system that maps to a Hona project. You must provide a projectId or a phone number. If both are provided, only the project id will be used.phoneNumber: The number to which you want to send a message. Use the phone number only if you are not providing a projectId. If both are present, only the projectId will be used. Some use cases: -- Message a client without a project -- Send a mass message when you don't want the message to show up in the conversation history.authorId: Used with a project id to add an author to the message in Hona. Without this, the message author will be listed as "CRM." In your CRM, this id identifies a team member or user account. It will only work if the user has been imported into Hona as a team member and has a user account. See users here: https://app.hona.com/company/settings/team
Example request body:
{ "projectId": "123-3123-123", "text": "New Project", "authorId": "32435", }Calendar Events
Create/Update a Calendar Event
To Send a Message, make a POST request to the following endpoint:
POST /calendar-event (<https://api.hona.com/partner/v2/calendar-event>)
Request Body
The request body should be a JSON object with the following fields:
id: The ID of the calendar event in your case management system.projectId: This is the ID of the object in your case management system (CMS) that maps to a Hona project.title: The name of the event that will be displayed to theattendees: Array of the ID of objects in your CMS that map to Hona contacts. It will only work if the contacts of your CMS have been imported into Hona as a team member and has a user account.teamMembers: Array of IDs of users in your CMS that map to Hona Team Members and are assigned to the Hona project. It will only work if the user has been imported into Hona as a team member and has a user account. See users here: https://app.hona.com/company/settings/teamotherMembers: Array of IDs of users in your CMS that map to Hona Team Members and are NOT assigned to the Hona project. It will only work if the user has been imported into Hona as a team member and has a user account. See users here: https://app.hona.com/company/settings/teamstartTime: The date and time that the calendar event starts.endTime (optional): The date and time the calendar event ends. If no value is provided, the default is 30 minutes.timezone: The timezone of the start/end timeslocation (optional): The location of the calendar event.description (optional): Any additional info you want to display on the event.reminder (optional): An array of objects containingunitandamountfields.unitrepresents the unit of time before the event starts and can beday,hour, orminute.amountis the number of units before thestartTimethe reminder is sent out. The reminder is sent as an SMS or email, depending on the contact notification preferences.
Example request body:
{ "id": "XYZ123" "projectId": "1234", "title": "Jane Smith Desposition", "attendees": ["[email protected]"], "teamMembers": ["[email protected]"], "otherMembers": ["[email protected]"], "startTime": "2024-01-01 08:00:00", "endTime": "2024-01-01 08:30:00", "timezone": "EST", "location": "1234 courtroom road, new york", "description": "this is a description", "reminders": [{unit: "day", amount:"1"}], "notify": true, }Delete a Calendar Event
To Send a Message, make a Delete request to the following endpoint:
DELETE /project/:projectId/calendar-event/:eventId?notify=true (<https://api.hona.com/partner/v2/project/:projectId/calendar-event/:eventId?notify=true>)
URL Params
The URL Params fields:
eventId: The ID of the calendar event in your case management system.projectId: This is the ID of the object in your case management system (CMS) that maps to a Hona project.notify: Optional query parameter to indicate if the attendees should be notified that the event was canceled.