Managing Contacts

In this section of our API guidebook we take a look at managing contacts. You can create, edit, and delete individual contacts as well as contact lists that group a set of contacts.

Create a Contact

POST /api/v3/contacts/

(* denotes required parameters)

Form Parameters:
 
  • name* – the name of the contact
  • email* – email address of the contact
  • <custom_field> – value of custom field, where <custom_field> is the name of an existing or new custom field
curl -u bob@example.com:PASSWORD -d "name=new guy&email=newguy@example.com" \
https://fluidsurveys.com/api/v3/contacts/
{"id": 8003316,
 "contact_uri": "https://fluidsurveys.com/api/v3/contacts/8003316/",
 "email": "newguy@example.com",
 "name": "new guy",
 "unsubscribed": false}

Edit a Contact

PUT /api/v3/contacts/:id/
Form Parameters:
 
  • name – updated name
  • email – updated email
  • <custom_field> – value of custom field, where <custom_field> is the name of an existing or new custom field
curl -u bob@example.com:PASSWORD -X PUT -d "name=New Guy" \
https://fluidsurveys.com/api/v3/contacts/8003316/
{"id": 8003316,
 "contact_uri": "https://fluidsurveys.com/api/v3/contacts/8003316/",
 "email": "newguy@example.com",
 "name": "New Guy",
 "unsubscribed": false}

Finding Contacts

GET /api/v3/contacts/
Query Parameters:
 
  • search – optional keyword to search for
Return a list of all contacts,
optionally filtered by the search query parameter.
curl -u bob@example.com:PASSWORD \
https://fluidsurveys.com/api/v3/contacts/?search=example.com
{"count": 1,
 "next": null,
 "previous": null,
 "results": [
   {"name": "New Guy",
    "email": "newguy@example.com",
    "id": 8003316,
    "contact_uri": "https://fluidsurveys.com/api/v3/contacts/8003316/",
    "unsubscribed": false
   }
  ]
}

Delete a Contact

DELETE /api/v3/contacts/:id/
curl -u bob@example.com:PASSWORD -X DELETE \
https://fluidsurveys.com/api/v3/contacts/8003316/
"OK"

Creating Lists

POST /api/v3/contact-lists/
Form Parameters:
 
  • name – name of contact list
  • color – hexadecimal color code
curl -u bob@example.com:PASSWORD -d "name=Employees" \
https://fluidsurveys.com/api/v3/contact-lists/
{"color": "#9eb7c8",
 "contacts_uri": "https://fluidsurveys.com/api/v3/contact-lists/96920/contacts/",
 "id": 96920,
 "name": "Employees",
 "contacts": 0
}

Adding a Contact to a List

Use an existing contact’s id to add it to a contact list, or create a new contact while adding it to a list by specifying the name and email.

POST /api/v3/contact-lists/:id/contacts/
Form Parameters:
 
  • id – a comma seperated list of contact ids
  • name – name of new contact
  • email – email of new contact
curl -u bob@example.com:PASSWORD -d "name=Brand New&email=brandnew@example.com" \
https://fluidsurveys.com/api/v3/contact-lists/96920/contacts/
{"count": 1,
 "next": null,
 "previous": null,
 "results": [{"id": 1,
 "name": "Bob",
 "email": "bob@example.com"}]
}