Add person

POST /people

Add a new person to the site which can include person, household, email, cell, phone, custom fields and adding them to a group (required when user is clustered)

There are few mandatory fields, these are determined by the configuration of the site. Specific custom fields can be set as mandatory for instance. The fields the authenticated user is allowed to set are determined by the permissions in the role, e.g. if the role is not allowed to see archived people, then the archive field cannot be set. Invalid field names, or valid field names that the authenticated user does not have access to are returned with the error "Invalid Field".

Mandatory custom fields. The rule is that if the authenticated user can see the field, then its mandatory. There are 2 ways a field is hidden:

a) The field is on the 'involvement' tab - visibility is controlled based on the role "Can edit involvement tab"

b) A contact type is identified, and Custom Views are setup, and the mandatory field is visible in that contact type.

This method means that you can have a contact type of a "Fence Post" which has some mandatory fields, and another that is "Individual" which has others, and only those mandatory fields that are for the type specified are checked.

application/json

Body Required

firstname string

Contacts first name. Mandatory
lastname string

Contacts last name. Mandatory
middlename string

Contacts middle name. Optional
title string

Contacts title. Optional
gender string

Contacts gender. Organisation can be used to determine an organisation contact. Optional.

Values are Male, Female, or ORGANISATION.
archived integer

Whether this contact is archived (1) or not (0). Optional. Will default to 0. Authenticated user must have access to archived people to be able to use this field.

Values are 0 or 1.
maritalStatus integer

The ID of the marital status lookup. Use the lookup/list end point to identify. Optional
occupation integer

The ID of the occupation list. Use the occupation/list end point to identify Optional
guardian integer

Whether this person is a guardian (1) or not (0) of children in this household. Optional

Values are 0 or 1.
dateOfBirth string

The date in local time. Use YYYY-MM-DD format. Optional but must be a date before or on todays date.
dateOfDeath string

The date in local time. Use YYYY-MM-DD format. Optional but must be a date before or on todays date.
salutation string

An alternative value to refer to this contact. Optional. Uses firstname if not provided.
nickname string

An alternative value to refer to this contact. Optional. Uses firstname if not provided.
userName string

Login name for the user - must be unique. Optional. Must have ability to "Create account and set roles" in authenticated uses role.
loginActive integer

Whether the login is active (1) or not (0). Optional. Must have ability to "Create account and set roles" in authenticated uses role.

Values are 0 or 1.
roleId integer

Role for this users login. See the role list end points. Optional. Must have ability to "Create account and set roles" in authenticated uses role.
preferredContactMethod string

Contacts preferred contact method. Optional Use these codes. EML: Email TXT: Text DOC: Letter TEL: Phone FB: Facebook SL: Slack CEL: Cell

Values are EML, TXT, DOC, TEL, FB, SL, or CEL.
organisationcontact string

Whether the contact is an Organisation Contact. If not used, you can use Gender field to set it - using ORGANISATION as the gender value. If set to Y, this overrides the setting in gender. Optional

Values are Y or N.
HouseholdName string

Either the Household or the Organisation Name. Optional
HouseNameNum string

For UK Addresses - used for Gift Aid claims, stores first part of the address. Optional.
Addressline1 string

Optional.
Addressline2 string

Optional.
Addressline3 string

Only used for sites in countries with this address line enabled. Optional.
Addressline4 string

Only used for sites in countries with this address line enabled. Optional.
Area string

The Area (also called suburb or state). Optional
City string

The City for the address. Optional
PostalCode string

The postcode (also called Zip code). Optional. Required for UK clients when they are used to make a claim.
CountryCode string

See the country list endpoint to get list of codes
HousedholdPhone string

The primary phone number for this household (or organisation). Optional
Fax string

The primary fax number for this household (or organisation). Optional
ReceiptToAlias string

Used when receipting to identify the name this receipt should be be issued to. Optional. The other names are used if this is not provided.
ReceiptTo string

The default Receipt To setting for transactions. Use the following codes. hh: Household (or organisation) ind: Individual

Values are hh or ind.
ReceiptToOneOff integer

The default setting as to how to combine transactions. Use the following codes. 0 : Combined 1 : One-off -1 : No receipt

Values are 0, 1, or -1.
email array[object]

A list of email addresses for this person
Hide email attributes Show email attributes object
- type string
  
  The text to describe the purpose or type of this email address. Optional
- value string
  
  The email address. Required
- active integer
  
  Whether this is an active email address (1) or not (0)
  
  Values are 0 or 1.
phone array[object]

A list of personal phone numbers for this person
Hide phone attributes Show phone attributes object
- type string
  
  The text to describe the purpose or type of this phone number. Optional
- value string
  
  The phone number. Required
cell array[object]

A list of personal cell phone (mobile) numbers for this person
Hide cell attributes Show cell attributes object
- type string
  
  The text to describe the purpose or type of this number. Optional
- value string
  
  The phone number. Required
customfield ID

if supplying a single custom field, you can use this method. Just provide the ID and the value. For a list of custom fields, use customfields property
customfields array[object]
This is an array of custom fields. Each array element includes:
- custom field id
- value Use the customfield list endpoint to determine the ID of the custom field you want to add along with its type type - can be string or integer as determined by the type of field
Lookup: Use the ID of the associated lookup using the lookup end point to inspect Multi Lookup: Use a comma separated list of IDs of the associated lookup
Hide customfields attributes Show customfields attributes object
- id integer
- value string
groups array[object]

The list of groups to add this contact to whilst loading. Because this is adding a person, then the group must be the 'child-most' group of a tree. infoodle will automatically add the person to all the parent groups as needed.

If the authenticated user is a Cluster'ed login, then this group field containing 1 or more groups is required. And the group must be part of the users cluster also. If the authenticated user is not clustered, then this is optional.
Hide groups attributes Show groups attributes object
- id integer
  
  The ID of the group. See the groups list end point.
- permission string
  
  The permission this contact has in the group. Choose from A: Admin F: Full member V: View only P: Past member
  
  Values are A, F, V, or P.
- functionid integer
  
  The ID of the function. Use the lookup list end point to identify the usage of group_function. Then the lookup endpoint to get the possible items. Optional.
- skillid integer
  
  The ID of the team skill. Use the lookup list end point to identify the usage of team_skills. Then the lookup endpoint to get the possible items. Optional.
- dateStarted string
  
  The date the person joined this group in YYYY-MM-DD format. This is optional, and will default to todays date if not supplied.
- dateLeft string
  
  The date the person left this group in YYYY-MM-DD format. This is optional unless the permission value is 'P' in which case its required. If not supplied then no value is used.
- parentPermission string
  
  What permission to give this person to any parent group of the identified group. Choose from A: Admin F: Full member V: View only P: Past member
  
  Values are A, F, V, or P.

Responses

200 application/json

OK
Hide response attributes Show response attributes object
- ok integer
  
  Whether the add worked (1) or not (0)
  
  Values are 0 or 1.
- id integer
  
  The User ID of the created contact. Returned if ok = 1
- errors array[object]
  
  A list of errors for each field in error. Returned if ok = 0. For multi lookup custom fields can return multiple errors for the one field.
  
  Hide errors attributes Show errors attributes object
  
  fieldname string
  
  The field name in error
  
  message string
  
  Description of the problem

POST /people

curl \
 --request POST 'https://YOURSITE.infoodle.com/apiv2/people' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --data '{"firstname":"John","lastname":"Smith","middlename":"Andrew","title":"Mr","gender":"Male","archived":0,"maritalStatus":9,"occupation":98,"guardian":1,"dateOfBirth":"1980-10-31","dateOfDeath":"2021-10-31","salutation":"Mr Jimmy James","nickname":"Jimmy","userName":"JohnSmith","loginActive":1,"roleId":43,"preferredContactMethod":"EML","organisationcontact":"N","HouseholdName":"The Jones Company Ltd","HouseNameNum":"The Vicarage","Addressline1":"1 The High Street","Addressline2":"1 Lower East Hampton","Addressline3":"string","Addressline4":"string","Area":"West Area","City":"Glasgow","PostalCode":"SW1A 1AA","CountryCode":"NZ","HousedholdPhone":"012 123 1234","Fax":"012 123 1234","ReceiptToAlias":"James' Institute","ReceiptTo":"hh","ReceiptToOneOff":1,"email":[{"type":"home","value":"c@b.com","active":1}],"phone":[{"type":"home","value":"+1 123 3214 1234"}],"cell":[{"type":"work","value":"+1 123 3214 1234"}],"customfields":[{"id":101,"value":"new text"}],"groups":[{"id":100,"permission":"F","functionid":214,"skillid":542,"dateStarted":"2022-05-01","dateLeft":"2022-07-01","parentPermission":"V"}]}'

Request examples

{
  "firstname": "John",
  "lastname": "Smith",
  "middlename": "Andrew",
  "title": "Mr",
  "gender": "Male",
  "archived": 0,
  "maritalStatus": 9,
  "occupation": 98,
  "guardian": 1,
  "dateOfBirth": "1980-10-31",
  "dateOfDeath": "2021-10-31",
  "salutation": "Mr Jimmy James",
  "nickname": "Jimmy",
  "userName": "JohnSmith",
  "loginActive": 1,
  "roleId": 43,
  "preferredContactMethod": "EML",
  "organisationcontact": "N",
  "HouseholdName": "The Jones Company Ltd",
  "HouseNameNum": "The Vicarage",
  "Addressline1": "1 The High Street",
  "Addressline2": "1 Lower East Hampton",
  "Addressline3": "string",
  "Addressline4": "string",
  "Area": "West Area",
  "City": "Glasgow",
  "PostalCode": "SW1A 1AA",
  "CountryCode": "NZ",
  "HousedholdPhone": "012 123 1234",
  "Fax": "012 123 1234",
  "ReceiptToAlias": "James' Institute",
  "ReceiptTo": "hh",
  "ReceiptToOneOff": 1,
  "email": [
    {
      "type": "home",
      "value": "c@b.com",
      "active": 1
    }
  ],
  "phone": [
    {
      "type": "home",
      "value": "+1 123 3214 1234"
    }
  ],
  "cell": [
    {
      "type": "work",
      "value": "+1 123 3214 1234"
    }
  ],
  "customfields": [
    {
      "id": 101,
      "value": "new text"
    }
  ],
  "groups": [
    {
      "id": 100,
      "permission": "F",
      "functionid": 214,
      "skillid": 542,
      "dateStarted": "2022-05-01",
      "dateLeft": "2022-07-01",
      "parentPermission": "V"
    }
  ]
}

Response examples (200)

{
  "ok": 1,
  "id": 123213,
  "errors": [
    {
      "fieldname": "firstname",
      "message": "Mandatory field not provided"
    }
  ]
}