Contact API FAQ

How-to search and list your contacts

Paging results:

>>> api.contact.list(apikey, {'items_per_page': 10, 'page': 0})

Sorting results:

>>> api.contact.list(apikey, {'sort_by' : 'handle desc'})

Available search filters are:

  • handle
  • orgname
  • given
  • family
  • type
  • email
  • zip
  • city
  • streetaddr
  • country

Listing all contacts with a email like ‘%mydomain%’:

>>> api.contact.list(apikey, {'~email': '%mydomain%'})

Listing contacts by type:

>>> api.contact.list(apikey, {'type': 0})

All together:

>>> api.contact.list(apikey, {
  'items_per_page': 10,
  'sort_by' : 'handle desc',
  'page': 1,
  'type': 0,
  })

How-to check domain/contact association

The Contact API contact.can_associate_domain() and contact.can_associate() allow you to check domain availability for a given contact (in a context of a contact registering, transferring, or updating the domain process).

Example: checking mydomain.fr availability for FLN123-GANDI, as admin and owner contact

>>> association_spec = {
...     'domain': 'mydomain.fr',
...     'owner': True,
...     'admin': True}
>>> api.contact.can_associate_domain(apikey, 'FLN123-GANDI', association_spec)
True
>>> res = api.contact.can_associate_domain(apikey, 'FLN123-GANDI', association_spec)
>>> [(x['field'], x['field_type'], x['error'], x['reason']) for x in res]
[('birth_city',
  'String',
  'EC_INVALIDPARAM1+EC_STRTOOFEWCHARS',
  "BirthCity: string '' has less than 1 characters"),
('birth_date',
  'Date',
  'EC_INTERNALERR2',
  "BirthDate: time data '' does not match format '%Y-%m-%d'"),
('birth_department',
  'String',
  'EC_INVALIDPARAM1+!EC_STRMATCH',
  "BirthDepartment: string '' does not match '^(2A|2B|\\d{1,3})$'"),
('birth_country',
  'Enum',
  'EC_INVALIDPARAM1+!EC_ENUMIN',
  'BirthCountryIso:  not in list AF,ZA,AL,DZ,DE,AD,AO,AI,AG,AN,SA,AR,AM,AW,AC,AU,AT,AZ,BS,BH,BD,BB,BY,BE,BZ,BJ,BM,BT,BO,BA,BW,BR,BN,BG,BF,BI,KH,CM,CA,CV,KY,CF,CL,CN,CY,CO,KM,CG,CD,CK,KR,KP,CR,CI,HR,CU,DK,DJ,DO,DM,EG,SV,AE,EC,ER,ES,EE,US,ET,FK,FO,FJ,FI,FR,GA,GM,GE,GH,GI,GR,GD,GL,GU,GT,GN,GQ,GW,GY,HT,HI,HN,HK,HU,IN,ID,IR,IQ,IE,IS,IL,IT,JM,JP,JE,JO,KZ,KE,KG,KI,KW,LA,LS,LV,LB,LR,LY,LI,LT,LU,MO,MK,MG,MY,MW,MV,ML,MT,MP,MA,MH,MU,MR,MX,FM,MD,MC,MN,MS,MZ,MM,NA,NR,NP,NI,NE,NG,NU,NF,NO,NZ,OM,UG,UZ,PK,PW,PS,PA,PG,PY,NL,PE,PH,PL,PT,PR,QA,RO,GB,RU,RW,SH,LC,KN,SM,VC,SB,AS,WS,ST,SN,SC,SL,SG,SK,SI,SO,SD,LK,SE,CH,SR,SZ,SY,TJ,TW,TZ,TD,CZ,TH,TP,TG,TK,TO,TT,TN,TM,TC,TR,TV,UA,UY,VU,VE,VI,VG,VN,YE,ZM,ZW,RE,PF,AQ,GF,NC,MQ,GP,PM,TF,YT,RS,TL,CC,CX,HM,AX,BV,GS,GG,IM,ME,IO,PN,EH,BL,MF,VA,SJ,WF,EP')]

<?php
$contact_api = XML_RPC2_Client::create($api_uri, array('prefix' => 'contact.'));
$association_spec = array(
        'domain' => 'mydomain.fr',
        'owner' => true,
        'admin' => true );
print_r( $contact_api->can_associate_domain($apikey, 'GG2647-GANDI', $association_spec) );
// 1
// OR
print_r( $contact_api->can_associate_domain($apikey, 'FLN123-GANDI', $association_spec) )
/*
[{'error': 'EC_INVALIDPARAM1+!EC_ENUMIN',
        'field': 'birth_country',
        'field_type': 'Enum',
        'reason': 'BirthCountryIso:  not in list ...
},... ]
*/
?>

> var association_spec = {
...   domain: 'mydomain.fr',
...   owner: true,
...   admin: true}
> api.methodCall('contact.can_associate_domain',
...    [apikey, 'FLN123-GANDI', association_spec],
...    function (error, value) {
...        console.dir(value)
... })

my $association_spec = {
    'domain' => 'mydomain.fr',
    'owner' => True,
    'admin' => True
};
my $result = $api->call( 'contact.can_associate_domain', $apikey, 'FLN123-GANDI', $association_spec );
print $result;
True
$result = $api->call( 'contact.can_associate_domain', $apikey, 'FLN123-GANDI', $association_spec );
print $result;
[{'error': 'EC_INVALIDPARAM1+!EC_ENUMIN',
'field': 'birth_country',
'field_type': 'Enum',
'reason': 'BirthCountryIso:  not in list ...
},... ]

association_spec = {
    'domain' => 'mydomain.fr',
    'owner'=> true,
    'admin'=> true
}
print server.call("contact.can_associate_domain", apikey, 'FLN123-GANDI', association_spec)
True
print server.call("contact.can_associate_domain", apikey, 'FLN123-GANDI', association_spec)
[{'error': 'EC_INVALIDPARAM1+!EC_ENUMIN',
'field': 'birth_country',
'field_type': 'Enum',
'reason': 'BirthCountryIso:  not in list ...
},... ]

In this example, birth_city, birth_date, birth_department and birth_country are missing or invalid contact attributes.

For each field, the method returns various information like the field type, the error type and the reason why it is incorrect (see error codes for a complete description of error types).

To modify your contact use the contact.update() method:

>>> contact_spec = {
  'extra_parameters': {
    'birth_city': 'Paris',
    'birth_date': '1980-01-01',
    'birth_department': '75',
    'birth_country': 'FR'}}
>>> contact = api.contact.update(apikey, 'FLN123-GANDI', contact_spec)
>>> api.contact.can_associate_domain(apikey, 'FLN123-GANDI', association_spec)
True

<?php
$contact_api = XML_RPC2_Client::create($api_uri, array('prefix' => 'contact.'));
$contact_spec = array(
  'extra_parameters' => array(
    'birth_city' => 'Paris',
    'birth_date' => '1980-01-01',
    'birth_department' => '75',
    'birth_country'=> 'FR' ));
$contact = $contact_api->update($apikey, 'FLN123-GANDI', $contact_spec) ;
print_r( $contact_api->can_associate_domain($apikey, $association_spec) );
// 1
?>

> var contact_spec = {
  extra_parameters: {
    birth_city: 'Paris',
    birth_date: '1980-01-01',
    birth_department: '75',
    birth_country: 'FR'}}
> api.methodCall('contact.update',
    [apikey, 'FLN123-GANDI', contact_spec],
    function (error, value) {
        console.dir(value)
 })

my $contact_spec = {
  'extra_parameters' => {
    'birth_city' => 'Paris',
    'birth_date' => '1980-01-01',
    'birth_department' => '75',
    'birth_country'=> 'FR'
  }
};

my $contact = $api->call( 'contact.update', $apikey, 'FLN123-GANDI', $contact_spec );
my $result = $api->call( 'contact.can_associate_domain', $apikey, $association_spec );
print $result;
1

contact_spec = {
  'extra_parameters' => {
    'birth_city' => 'Paris',
    'birth_date' => '1980-01-01',
    'birth_department' => '75',
    'birth_country'=> 'FR'
  }
}

contact = server.call("contact.update", apikey, 'FLN123-GANDI', contact_spec)
result = server.call("contact.can_associate_domain", association_spec)
print result
true

The contact.can_associate() method allows you to check domain/contact association rules according to contact specifications:

>>> association_spec = {
...     'domain': 'mydomain.fr',
...     'owner': True,
...     'admin': True}
>>> contact_spec = {
...     'type': 0,
...     'given': 'Given',
...     'family': 'Family',
...     'password': 'PassworD',
...     'email': 'given@family.net',
...     'phone': '+33123456789',
...     'streetaddr': 'my street',
...     'city': 'My City',
...     'zip': '75000',
...     'country': 'FR'}
>>> api.contact.can_associate(apikey, contact_spec, association_spec)
[{'error': 'EC_INVALIDPARAM1+!EC_ENUMIN',
'field': 'birth_country',
'field_type': 'Enum',
'reason': 'BirthCountryIso:  not in list ...
},... ]
>>> api.contact.can_associate(apikey, contact_spec, association_spec)
True

<?php
$contact_api = XML_RPC2_Client::create($api_uri, array('prefix' => 'contact.'));
$association_spec = array(
        'domain' => 'mydomain.fr',
        'owner' => true,
        'admin' => true );
$contact_spec = array(
        'type' => 0,
        'given' => 'Given',
        'family' => 'Family',
        'password' => 'PassworD',
        'email' => 'given@family.net',
        'phone' => '+33123456789',
        'streetaddr' => 'my street',
        'city' => 'My City',
        'zip' => '75000',
        'country' => 'FR' );
print_r( $contact_api->can_associate($apikey, $contact_spec, $association_spec) );
// 1
// OR
print_r( $contact_api->can_associate($apikey, $contact_spec, $association_spec) )
/*
[{'error': 'EC_INVALIDPARAM1+!EC_ENUMIN',
        'field': 'birth_country',
        'field_type': 'Enum',
        'reason': 'BirthCountryIso:  not in list ...
},... ]
*/
?>

> var association_spec = {
...   domain: 'mydomain.fr',
...   owner: true,
...   admin: true}
> var contact_spec = {
...   type: 0,
...   given: 'Given',
...   family: 'Family',
...   password: 'PassworD',
...   email: 'given@family.net',
...   phone: '+33123456789',
...   streetaddr: 'my street',
...   city: 'My City',
...   zip: '75000',
...   country: 'FR'}
> api.methodCall('contact.can_associate',
...    [apikey, contact_spec, association_spec],
...    function (error, value) {
...        console.dir(value)
... })

my $association_spec = {
    domain => 'mydomain.fr',
    owner => True,
    admin => True
};
my $contact_spec = {
    type => 0,
    given => 'Given',
    family => 'Family',
    password => 'PassworD',
    email => 'given@family.net',
    phone => '+33123456789',
    streetaddr => 'my street',
    city => 'My City',
    zip => '75000',
    country => 'FR'
};

my $result = $api->call( 'contact.can_associate', $apikey, $contact_spec, $association_spec );
print $result;
[{'error': 'EC_INVALIDPARAM1+!EC_ENUMIN',
'field': 'birth_country',
'field_type': 'Enum',
'reason': 'BirthCountryIso:  not in list ...
},... ]
my $result = $api->call( 'contact.can_associate', $apikey, $contact_spec, $association_spec );
print $result;
True

association_spec = {
    'domain' => 'mydomain.fr',
    'owner'=> true,
    'admin'=> true
}
contact_spec = {
        'type' => 0,
        'given' => 'Given',
        'family' => 'Family',
        'password' => 'PassworD',
        'email' => 'given@family.net',
        'phone' => '+33123456789',
        'streetaddr' => 'my street',
        'city' => 'My City',
        'zip' => '75000',
        'country' => 'FR'
}

print server.call("contact.can_associate", apikey, contact_spec, association_spec)
[{'error': 'EC_INVALIDPARAM1+!EC_ENUMIN',
'field': 'birth_country',
'field_type': 'Enum',
'reason': 'BirthCountryIso:  not in list ...
},... ]
print server.call("contact.can_associate", apikey, contact_spec, association_spec)
True