BaseCRM Official API V2 library client for Python
BaseCRM package can be installed either via pip or easy_install:
$ pip install --upgrade basecrm
or
$ easy_install --upgrade basecrm
You can install from the source code as well. First clone the repo and then execute:
$ python setup.py install
After installing, import basecrm
package:
import basecrm
import basecrm
# Then we instantiate a client (as shown below)
Using this api without authentication gives an error
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
The following options are available while instantiating a client:
- access_token: Personal access token
- base_url: Base url for the api
- user_agent: Default user-agent for all requests
- timeout: Request timeout
- verbose: Verbose/debug mode
The library follows few architectural principles you should understand before digging deeper. 1. Interactions with resources are done via service objects. 2. Service objects are exposed as properties on client instances. 3. Service objects expose resource-oriented actions. 4. Actions return dictionaries that support attribute-style access, a la JavaScript (thanks to Bunch and it's form Munch).
For example, to interact with deals API you will use
basecrm.DealsService
, which you can get if you call:
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.deals # basecrm.DealsService
To retrieve list of resources and use filtering you will call #list
method:
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.deals.list(organization_id=google.id, hot=True) # list(dict|Munch)
To find custom field by name and its value pass kwargs as an argument:
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.deals.list(**{'custom_fields[name]': 1})
To find a resource by its unique identifier use #retrieve
method:
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.deals.retrieve(id=google.id)
When you'd like to create a resource, or update it's attributes you want
to use either #create
or #update
methods. For example if you
want to create a new deal you will call:
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
deal = client.deals.create(name='Website redesign', contact_id=coffeeshop.id)
deal.value = Decimal("1000.99")
deal.currency = 'USD'
client.deals.update(deal.id, deal)
To destroy a resource use #destroy
method:
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.deals.destroy(coffeshopdeal.id)
There other non-CRUD operations supported as well. Please contact corresponding service files for in-depth documentation.
Create a new organization and after that change it's attributes (website).
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
lead = client.leads.create(organization_name='Design service company')
lead.website = 'http://www.designservices.com'
client.leads.update(lead.id, lead)
You can control the maximum number of records that are returned using the standard per_page query parameter. To choose a page, use the standard page query parameter. The default page is always the first one. The default limit is 25 and maximum number that can be returned is 100.
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
leads = client.leads.list(per_page=50, page=2)
When you instantiate a client or make any request via service objects, exceptions can be raised for multiple of reasons e.g. a network error, an authentication error, an invalid param error etc.
Sample below shows how to properly handle exceptions:
try:
# Instantiate a client.
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
lead = client.leads.create(organization_name='Design service company')
print lead
except basecrm.ConfigurationError as e:
# Invalid client configuration option
pass
except basecrm.ResourceError as e:
# Resource related error
print 'Http status = ' + e.http_status
print 'Request ID = ' + e.logref
for error in e.errors:
print 'field = ' + error.field
print 'code = ' + error.code
print 'message = ' + error.message
print 'details = ' + error.details
except basecrm.RequestError as e:
# Invalid query parameters, authentication error etc.
pass
except Exception as e:
# Other kind of exceptioni, probably connectivity related
pass
The following sample code shows how to perform a full synchronization flow using high-level wrapper.
First of all you need an instance of basecrm.Client
. High-level basecrm.Sync
wrapper uses basecrm.SyncService
to interact with the Sync API.
In addition to the client instance, you must provide a device’s UUID within device_uuid
parameter. The device’s UUID must not change between synchronization sessions, otherwise the sync service will not recognize the device and will send all the data again.
client = basecrmClient(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
sync = basecrm.Sync(client=client, device_uuid='<YOUR_DEVICES_UUID')
Now all you have to do is to call fetch
method and pass a lambda or function that you might use to store fetched data to a database.
def synchronize(meta, data):
result = DAO.execute(table=meta.type,
statement=meta.sync.event_type,
properties=data)
return basecrm.Sync.ACK if result else basecrm.sync.NACK
sync.fetch(synchronize)
Notice that you must return either basecrm.Sync.ACK
or basecrm.Sync.NACK
.
Documentation for every action can be found in basecrm/services.py
file.
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.accounts # => basecrm.AccountsService
Actions:
- Retrieve account details -
client.accounts.self
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.associated_contacts # => basecrm.AssociatedContactsService
Actions:
- Retrieve deal's associated contacts -
client.associated_contacts.list
- Create an associated contact -
client.associated_contacts.create
- Remove an associated contact -
client.associated_contacts.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.contacts # => basecrm.ContactsService
Actions:
- Retrieve all contacts -
client.contacts.list
- Create a contact -
client.contacts.create
- Retrieve a single contact -
client.contacts.retrieve
- Update a contact -
client.contacts.update
- Delete a contact -
client.contacts.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.deals # => basecrm.DealsService
Actions:
- Retrieve all deals -
client.deals.list
- Create a deal -
client.deals.create
- Retrieve a single deal -
client.deals.retrieve
- Update a deal -
client.deals.update
- Delete a deal -
client.deals.destroy
A note about deal value
It is prefered to use decimal from string or directly string for deal values when creating or modifying a deal. This guarantees correct precision
deal.value = Decimal("1000.99")
deal.value = "1000.00"
You should not be using floats or decimal constructed from floats as it may result in precision loss.
deal.value = 1000.99
deal.value = decimal(1000.99)
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.deal_sources # => basecrm.DealSourcesService
Actions:
- Retrieve all sources -
client.deal_sources.list
- Create a new source -
client.deal_sources.create
- Retrieve a single source -
client.deal_sources.retrieve
- Update a source -
client.deal_sources.update
- Delete a source -
client.deal_sources.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.deal_unqualified_reasons # => basecrm.DealUnqualifiedReasonsService
Actions:
- Retrieve all deal unqualified reasons -
client.deal_unqualified_reasons.list
- Create a deal unqualified reason -
client.deal_unqualified_reasons.create
- Retrieve a single deal unqualified reason -
client.deal_unqualified_reasons.retrieve
- Update a deal unqualified reason -
client.deal_unqualified_reasons.update
- Delete a deal unqualified reason -
client.deal_unqualified_reasons.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.leads # => basecrm.LeadsService
Actions:
- Retrieve all leads -
client.leads.list
- Create a lead -
client.leads.create
- Retrieve a single lead -
client.leads.retrieve
- Update a lead -
client.leads.update
- Delete a lead -
client.leads.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.lead_sources # => basecrm.LeadSourcesService
Actions:
- Retrieve all sources -
client.lead_sources.list
- Create a new source -
client.lead_sources.create
- Retrieve a single source -
client.lead_sources.retrieve
- Update a source -
client.lead_sources.update
- Delete a source -
client.lead_sources.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.lead_unqualified_reasons # => basecrm.LeadUnqualifiedReasonsService
Actions:
- Retrieve all lead unqualified reasons -
client.lead_unqualified_reasons.list
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.line_items # => basecrm.LineItemsService
Actions:
- Retrieve order's line items -
client.line_items.list
- Create a line item -
client.line_items.create
- Retrieve a single line item -
client.line_items.retrieve
- Delete a line item -
client.line_items.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.loss_reasons # => basecrm.LossReasonsService
Actions:
- Retrieve all reasons -
client.loss_reasons.list
- Create a loss reason -
client.loss_reasons.create
- Retrieve a single reason -
client.loss_reasons.retrieve
- Update a loss reason -
client.loss_reasons.update
- Delete a reason -
client.loss_reasons.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.notes # => basecrm.NotesService
Actions:
- Retrieve all notes -
client.notes.list
- Create a note -
client.notes.create
- Retrieve a single note -
client.notes.retrieve
- Update a note -
client.notes.update
- Delete a note -
client.notes.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.orders # => basecrm.OrdersService
Actions:
- Retrieve all orders -
client.orders.list
- Create an order -
client.orders.create
- Retrieve a single order -
client.orders.retrieve
- Update an order -
client.orders.update
- Delete an order -
client.orders.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.pipelines # => basecrm.PipelinesService
Actions:
- Retrieve all pipelines -
client.pipelines.list
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.products # => basecrm.ProductsService
Actions:
- Retrieve all products -
client.products.list
- Create a product -
client.products.create
- Retrieve a single product -
client.products.retrieve
- Update a product -
client.products.update
- Delete a product -
client.products.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.sources # => basecrm.SourcesService
Actions:
- Retrieve all sources -
client.sources.list
- Create a source -
client.sources.create
- Retrieve a single source -
client.sources.retrieve
- Update a source -
client.sources.update
- Delete a source -
client.sources.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.stages # => basecrm.StagesService
Actions:
- Retrieve all stages -
client.stages.list
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.tags # => basecrm.TagsService
Actions:
- Retrieve all tags -
client.tags.list
- Create a tag -
client.tags.create
- Retrieve a single tag -
client.tags.retrieve
- Update a tag -
client.tags.update
- Delete a tag -
client.tags.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.tasks # => basecrm.TasksService
Actions:
- Retrieve all tasks -
client.tasks.list
- Create a task -
client.tasks.create
- Retrieve a single task -
client.tasks.retrieve
- Update a task -
client.tasks.update
- Delete a task -
client.tasks.destroy
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.text_messages # => basecrm.TextMessagesService
Actions:
- Retrieve text messages -
client.text_messages.list
- Retrieve a single text message -
client.text_messages.retrieve
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.users # => basecrm.UsersService
Actions:
- Retrieve all users -
client.users.list
- Retrieve a single user -
client.users.retrieve
- Retrieve an authenticating user -
client.users.self
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.visits # => basecrm.VisitsService
Actions:
- Retrieve visits -
client.visits.list
client = basecrm.Client(access_token='<YOUR_PERSONAL_ACCESS_TOKEN>')
client.visit_outcomes # => basecrm.VisitOutcomesService
Actions:
- Retrieve visit outcomes -
client.visit_outcomes.list
To run all test suites:
$ python setup.py test
And to run a single suite:
$ python setup.py test -s basecrm.test.test_associated_contacts_service.AssociatedContactsServiceTests
We would like to give huge thanks to YunoJuno. They reqlinquished the package name so we were able to publish official wrapper under basecrm name.
Thank You!
MIT
Report here.
BaseCRM developers (developers@getbase.com)