-
Notifications
You must be signed in to change notification settings - Fork 52
hapipy documentation
hapipy is a Python wrapper for the HubSpot APIs. You can find more information about HubSpot's APIs here: http://docs.hubapi.com. The hapipy wrapper is meant to make it easier for external developers to use the HubSpot APIs by giving easy access to data that gets returned to you after an API call gets made.
The following documentation will describe the different calls that you can make via the hapipy wrapper and includes some sample code for how to make these calls and deal with the responses. Please keep in mind that we'll be working hard to improve and add to this wrapper as we add to and iterate on our APIs so if a method that you're looking for isn't here today, please check back soon!
The base hapi.py includes all of the methods that you can call to use the wrapper. As I mentioned above, we're in progress with this and will continue to develop out different methods for all of our APIs going forward. The other files to note are the objects files which include all of the classes and define the data that you can access with each call you make. For the leads methods please refer to "lead_objects.py", for blog please refer to "blog_objects.py", for lead nurturing...well you get the idea.
Please refer to the the 'lead_objects.py' file in the repository for reference to the fields that are available to you on each Lead object.
-
get_lead: Lets you search for a specific lead by its GUID and returns a lead object. For more information on this operation, please [click here.] (http://docs.hubapi.com/wiki/Searching_Leads)
Required Parameters: Lead GUID
Example Call:
hs_client = HubSpotLeadsClient("demo")
lead = hs_client.get_lead("8a706adf3282b1e3013282b27b180011")
print lead.guid -
search_leads: Lets you search for leads by name, email address and company. For more information on this operation, please [click here.] (http://docs.hubapi.com/wiki/Searching_Leads)
Required Parameters: Search Parameter
Example Call:
hs_client = HubSpotLeadsClient("demo")
leads = hs_client.search_leads("Maxey")
for lead in leads:
print lead.guid -
update_lead: Lets you update a lead's information within HubSpot. This is useful for updating after a lead re-converts. It can also be useful to change a lead's grade (the "score" field).
This method will let you return any lead field like the previous methods listed above. If the update of your lead fails however, it will return a bit of JSON code to you with the HTTP status and message (reason the failure occurred).
For more information on this operation, please [click here.] (http://docs.hubapi.com/wiki/Updating_Leads)
Required Parameters: Lead Guid, Update data (in key:value pair format as shown below in the method call)
Example Call:
hs_client = HubSpotLeadsClient("demo")
new_lead = hs_client.update_lead("8a706adf3240e8c7013240ea3d7c01b4", {"email":"[email protected]"})
print new_lead.email -
offset_leads: Enables you to specify an "offset" on your call to the Leads API. This is useful for paginating leads, as the maximum amount of leads that can be returned to you in one API call is 100. Offset lets you start your leads call at lead "offset". For more information on this operation, please [click here.] (http://docs.hubapi.com/wiki/Searching_Leads)
Required Parameters: offset value
Example Call:
hs_client = HubSpotLeadsClient("demo")
leads = hs_client.offset_leads("100")
for lead in leads:
print lead.guid -
register_webhook: Lets you register a HubSpot Leads API webhook.
Required Parameters: endpoint URL
Example Call:
hs_client = HubSpotLeadsClient("demo")
webhook = hs_client.register_webhook("https://examplesite.com/webhook/endpoint/") -
close_lead: Enables you to close a lead in HubSpot. This operation will convert a lead from its current lead status to a customer status and will be reflected as such in HubSpot's analytics. If you call this method without a "close time", the lead will be closed using the current time as the close time. For more information on this operation, please [click here.] (http://docs.hubapi.com/wiki/Updating_Leads)
Required Parameters: Lead Guid, Close Time (optional) represented in unix time (milliseconds since the epoch). Example Call:
hs_client = HubSpotLeadsClient("demo")
new_lead = hs_client.close_lead("731d51afde694045a523ca83c15a06ec", "353894400000")
print new_lead.is_customer
Please refer to the 'lead_nurturing_objects.py' file in the repository for reference to the fields that are available to you on each Lead Nurturing object.
-
get_campaigns: This method enables you to get all ACTIVE campaigns for a given portal that have been created. For more information on this method, please [click here.] (http://docs.hubapi.com/wiki/Lead_Nurturing_API#Get_Campaign_Details)
Required Parameters: None
Example Call:
hs_client = HubSpotLeadNurtureClient("demo")
new_cams = hs_client.get_campaigns()
for lns in new_cams:
print lns.guid -
get_leads: This method enables you to get all leads who are enrolled in a particular lead nurturing campaign. For more information on this method, please [click here.] (http://docs.hubapi.com/wiki/Lead_Nurturing_API#Get_Leads_in_a_Campaign)
Required Parameters: Campaign Guid
Example Call:
hs_client = HubSpotLeadNurtureClient("demo")
new_cams = hs_client.get_leads("4159b174-8aeb-4746-abdc-9dfe013d47dc")
for lns in new_cams:
print lns.leadGuid -
get_history: This action will give you the Lead Nurturing history of the specified lead. For more information on this method, please [click here.] (http://docs.hubapi.com/wiki/Lead_Nurturing_API#Get_Campaign_History_for_a_Lead)
Required Parameters: Lead Guid
Example Call:
hs_client = HubSpotLeadNurtureClient("demo")
new_cams = hs_client.get_leads("8a706adf32691328013269138e9a0008")
for lns in new_cams:
print lns.leadGuid -
enroll_lead: This action will enroll a specified lead into a specified HubSpot lead nurturing campaign. It doesn't return anything but a simple string with some messaging as to the call made For reference and more information on this method, please [click here.] (http://docs.hubapi.com/wiki/Lead_Nurturing_API#Enroll_a_Lead_in_a_Campaign)
Required Parameters: Campaign Guid, Lead Guid
Example Call:
hs_client = HubSpotLeadNurtureClient("demo")
new_cams = hs_client.enroll_lead("4159b174-8aeb-4746-abdc-9dfe013d47dc", "8a706adf32691328013269138e9a0008")
print new_cams -
unenroll_lead: This action will remove a specified lead from a specified HubSpot lead nurturing campaign. It doesn't return anything but a simple string with some messaging as to the call made For reference and more information on this method, please [click here.] (http://docs.hubapi.com/wiki/Lead_Nurturing_API#Remove_a_Lead_from_a_Campaign)
Required Parameters: Campaign Guid, Lead Guid
Example Call:
hs_client = HubSpotLeadNurtureClient("demo")
new_cams = hs_client.enroll_lead("4159b174-8aeb-4746-abdc-9dfe013d47dc", "8a706adf32691328013269138e9a0008")
print new_cams
Please refer to the the 'blog_objects.py' file in the repository for reference to the fields that are available to you on each Lead object.
-
get_blogs: The get_blogs method returns information about the blogs within a specific portal, referenced by your API key. For more information on this method, please [click here.] (http://docs.hubapi.com/wiki/Blog_API_Methods#List_Blogs_for_a_Specific_API_Key)
Required Parameters: None
Example Call:
hs_client = HubSpotBlogClient("demo")
new_blog = hs_client.get_blogs()
for blogs in new_blog:
print blogs.guid -
get_blog_info: For a given blog, as identified by its GUID, list metadata. In the future, we can add things like total number of posts, number of pending draft posts, etc here. For more information about this method, click here.
Required Parameters: Blog GUID
Example Call:
hs_client = HubSpotBlogClient("demo")
new_blog = hs_client.get_blog_info("83dbb7ba-fa1b-49f7-8a1e-b8cc59d9b783")
print new_blog.web_url -
get_posts: For a given blog, as identified by its GUID, list posts. The default listing is for the ten most recent posts, in order from the most recently published backwards. For more information about this method, click here.
Required Parameters: Blog GUID
Example Call:
hs_client = HubSpotBlogClient("demo")
new_blog = hs_client.get_posts("83dbb7ba-fa1b-49f7-8a1e-b8cc59d9b783")
for blog_posts in new_blog:
print blog_posts.post_guid -
get_drafts: For a given blog, as identified by its GUID, list posts that are in Draft stage ONLY. The default listing is for the ten most recent posts, in order from the most recently published backwards.
Required Parameters: Blog GUID
Example Call:
hs_client = HubSpotBlogClient("demo")
new_blog = hs_client.get_drafts("83dbb7ba-fa1b-49f7-8a1e-b8cc59d9b783")
for blog_posts in new_blog:
print blog_posts.post_guid -
get_published_posts: For a given blog, as identified by its GUID, list posts that have been published ONLY. The default listing is for the ten most recent posts, in order from the most recently published backwards.
Required Parameters: Blog GUID
Example Call:
hs_client = HubSpotBlogClient("demo")
new_blog = hs_client.get_published_posts("83dbb7ba-fa1b-49f7-8a1e-b8cc59d9b783")
for blog_posts in new_blog:
print blog_posts.post_guid -
get_blog_comments: For a given blog, as identified by its GUID, list all of its comments. For more information about this method, click here.
Required Parameters: Blog GUID
Example Call:
hs_client = HubSpotBlogClient("demo")
new_blog_comments = hs_client.get_blog_comments("83dbb7ba-fa1b-49f7-8a1e-b8cc59d9b783")
for comments in new_blog_comments:
print comments.comment_guid -
get_post: For a specific blog post, identified by its GUID, list information. For more information about this method, click here.
Required Parameters: Blog Post GUID
Example Call:
hs_client = HubSpotBlogClient("demo")
new_blog = hs_client.get_post("9bd72b73-be8c-4afa-8d54-07c5b0d60a41")
print new_blog.post_guid -
get_post_comments: For a given blog post, as identified by its GUID, list its comments. For more information about this method, click here.
Required Parameters: Blog Post GUID
Example Call:
hs_client = HubSpotBlogClient("demo")
new_blog_comments = hs_client.get_post_comments("9bd72b73-be8c-4afa-8d54-07c5b0d60a41")
for comments in new_blog_comments:
print comments.comment_guid -
get_comment: For a given comment, identified by its comment GUID, list metadata and other information. We'll likely add more metadata here in the future. For more information about this method, click here.
Required Parameters: Blog Comment GUID
Example Call:
hs_client = HubSpotBlogClient("demo")
new_blog_comment = hs_client.get_comment("595da793-df5a-4ef4-aaa9-d1cacb53637c")
print new_blog_comment.comment_author_name -
create_post: For a given blog, as identified by its GUID, create a new draft blog post. When creating a new post the author for your post must be a registered and active HubSpot user's email address, otherwise you'll receive a 400 Bad Request error from the API. For more information about this method, click here.
Required Parameters: Blog GUID, Author Name (MUST be a valid user in the HubSpot portal), Author Email, Post Title, Post Summary, Post Content, Post Tags
Example Call:
new_blog_post = hs_client.create_post("83dbb7ba-fa1b-49f7-8a1e-b8cc59d9b783", "Blog API Test", "[email protected]", "Sample Blog Post", "Sample Blog Post Summary", "This is the sample blog post content", "test")
print new_blog_post.post_id -
update_post: For a given blog post, as identified by its GUID, you can update any subset of the fields you post new values for. Tags can also be updated this way, but any existing tags will be replaced with the new set of tags you assign. This means that whatever tags the post previously had that are not included in the new post will be explicitly removed from the post. Fields like id,hs:portalId, hs:blogGuid, hs:postAnalytics are read-only, cannot be updated, and will be ignored. Only the fields you use to create a post can be updated (body, title, summary, categories, hs:metaDescription, hs:metaKeywords, etc.). For more information about this method, click here.
Required Parameters: Blog Post GUID, Post Title, Post Summary, Post Content, Meta Description, Meta Keywords, Post Tags
Example Call:
new_blog_post = hs_client.update_post("f709a0a6-7f66-4d3b-bef3-73aea957025d", "Sample Blog Post", "Sample Blog Post Summary", "This is the sample blog post content", "sample keyword", "sample desc", "test")
print new_blog_post.post_id -
publish_post: For a given blog post, as identified by its GUID, you can update it and set it as published. When publishing posts you must pay close attention to three fields
- published - This is an ISO-8601 formatted date string in UTC time (see [ISO-8601 Format|http://en.wikipedia.org/wiki/ISO_8601] for more details), if this is not specified it will be 30 minutes in the future from when you API call is made, if you enable sending notifications and the publish time is less than 30 minutes in the future, you will receive a 400 error.
- hs:sendNotifications - if false then email and social media notifications will be not be sent. If not specified or explicitly set to true, then the email and social media notifications will go out as normal.
-
hs:draft - in order to publish a post, set this to false, otherwise, this will simply be viewed as a normal update to the blog post, and no publishing-related fields will be updated.
For more information about this method, click here.
Required Parameters: Blog Post GUID, Publish Time (the time you want to push the post live), Is Draft (set this to false to publish your post), Notify Social Media (set this to true to send out social media updates through HubSpot).
Example Call:
hs_client = HubSpotBlogClient("demo")
new_blog_post = hs_client.publish_post("f709a0a6-7f66-4d3b-bef3-73aea957025d", "2011-03-13T18:30:02Z", "true", "true")
print new_blog_post.post_id
-
create_comment: For a given blog post, as identified by its GUID, create a new comment. For more information about this method, click here.
Required Parameters: Blog Post GUID, Comment Author Name, Comment Author Email, Comment Author URL, Comment Content
Example Call:
new_blog_comment = hs_client.create_comment("9bd72b73-be8c-4afa-8d54-07c5b0d60a41", "Blog API Test", "[email protected]", "http://hubspot.com", "Test Comment 123")
print new_blog_comment.comment_guid
Please see http://docs.hubapi.com/wiki/Prospects_API for the main Prospects API documentation. Then read the [prospects API client] (https://github.com/HubSpot/hapipy/blob/master/hapi/prospects.py) and [unit tests] (https://github.com/HubSpot/hapipy/blob/master/hapi/test/test_prospects.py) to see code examples.