home / skills / abdullahbeam / nexus-design-abdullah / hubspot-create-contact
This skill creates a new HubSpot contact from an email and optional details, streamlining CRM entry and data consistency.
npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill hubspot-create-contactReview the files below or copy the command above to add this skill to your agents.
---
name: hubspot-create-contact
description: "Create a new contact in HubSpot CRM. Load when user says 'create contact', 'add contact', 'new contact'. Requires email, optional firstname, lastname, phone, company."
---
# Create HubSpot Contact
**Specialized skill** for creating contacts in HubSpot CRM.
## Pre-Flight Check
Before running, execute config check:
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json
```
If `ai_action` is not `proceed_with_operation`, follow hubspot-connect setup guide.
---
## Usage
### Required Parameters
- `--email` - Contact email address (required)
### Optional Parameters
- `--firstname` - First name
- `--lastname` - Last name
- `--phone` - Phone number
- `--company` - Company name
### Examples
**Minimal (email only):**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/create_contact.py \
--email "[email protected]" \
--json
```
**Full contact:**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/create_contact.py \
--email "[email protected]" \
--firstname "John" \
--lastname "Doe" \
--phone "+1234567890" \
--company "Acme Corp" \
--json
```
---
## Output Format
```json
{
"id": "12345",
"properties": {
"email": "[email protected]",
"firstname": "John",
"lastname": "Doe",
"createdate": "2025-12-13T10:00:00Z"
}
}
```
---
## Display Format
```
✅ Contact created!
ID: 12345
Name: John Doe
Email: [email protected]
Phone: +1234567890
Company: Acme Corp
```
---
## Error Handling
| Error | Solution |
|-------|----------|
| 401 | Invalid token - re-run setup |
| 403 | Missing `crm.objects.contacts.write` scope |
| 409 | Contact already exists with this email |
| 429 | Rate limited - wait and retry |
---
## Related Skills
- `hubspot-list-contacts` - List all contacts
- `hubspot-search-contacts` - Find existing contacts
- `hubspot-update-contact` - Update contact details
This skill creates a new contact record in HubSpot CRM from a simple command. It requires an email and accepts optional firstname, lastname, phone, and company fields. The skill validates configuration before running and returns the created contact ID and properties on success.
The skill runs a pre-flight configuration check to ensure HubSpot credentials and scopes are valid. It then calls the HubSpot Contacts API to create a contact with the provided fields and returns a JSON object containing the contact ID and properties. Errors such as authentication failures, missing scopes, duplicates, or rate limits are surfaced with clear codes and remedies.
What minimum information do I need to create a contact?
An email address is required; firstname, lastname, phone, and company are optional.
What do common error codes mean and how do I fix them?
401 means invalid token—re-run setup; 403 means missing crm.objects.contacts.write scope—grant the scope; 409 indicates the email already exists—search then update; 429 means rate limited—wait and retry with backoff.
How is the created contact returned?
On success the skill returns JSON with the contact id and a properties object containing fields such as email, firstname, lastname, and createdate.